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PREFACE 


This manual describes the use of PL/I in a GCOS environment for Series’ 60 
(Level 66)/6000 systems. The manual includes information on the execution of a 
PL/I program, file generation and access, compiler processing, loader functions, 
required control cards, and internal representation of PL/I data. Also, 
examples are included which are complete and executable. These examples contain 
the control cards and data necessary for execution; in addition sample output 
listings produced from the execution of some of these programs are also given. 
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SECTION | 


INTRODUCTION 


This manual describes the ways in which the general facilities of the 
General Comprehensive Operating Supervisor (GCOS) are applied to the specific 
tasks of compiling, loading, and executing PL/I programs, 


DESCRIPTION OF THE MANUAL 


The scope and structure of the User's Guide are described in the following 
paragraphs and then a list of related manuals is given. 


scope of the Manual 


This User's Guide is a self-contained and complete introduction to the use 
of PL/I for the Series 60 (Level 66)/6000 (hereafter referred to as Series 60). 
Therefore, it contains some basic information about GCOS to aid the programmer 
using this system for the first time. The necessary control cards, for example, 
are described and illustrated. Whenever a basic Series 60 concept is discussed, 
a reference is given to the manual that contains the detailed description. 
However, the information given in this manual about these concepts is sufficient 
for their initial use. 


Many examples are included in this manual. These examples are complete and 
executable; they contain all the control cards and data necessary for their 
execution. Also included are sample output listings produced from the execution 
of some of these programs. 


Structure of the Manual 


The sections of the User's Guide are ordered to provide, first the basic 
information about the use of the Series 60, then the details on the use of PL/I, 
and finally guidelines and examples. 


After the introductory material, the control cards required to compile and 
execute a PL/I program are given and the use of the standard input and output 
files is described. The sections that cover this material are: 


Execution of a PL/I Program 


1 | 
ltl System Input/Output Files 
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Next, detailed descriptions are given for the two large system programs involved 
in compilation and execution, namely: the compiler and the loader. The 
characteristics of the compiler are described and the compiler output listing is 
explained and illustrated. The relevant loader control cards are given and the 
overlay capability is described. The sections are: 


IV Compiler 
V Loader 


Next, the use of external files is described. For each type of organization, 
the method of attachment and an example of file access are given. The sections 
are: 


Vi External Files | 
VII CONSECUTIVE and INTERACTIVE Organization 
Vill INDEXED Organization 


|X REGIONAL Organization 


Next, some details of the compiler program are given. The method of linking 
PL/! programs with programs written in other languages is described. The 
internal representation of PL/! data is described and storage layout rules for 
variables given. The sections are: 


X Linking PL/I and Other Languages 
X | Internal Representation of PL/I Data 


Next, examples of the creation, modification, and use of the INCLUDE file are 
given. The section is: 


Xt! INCLUDE Files 


Next, a detailed description of debugging PL/I programs is presented. The 
messages printed upon the abnormal termination of a job are discussed and _ the 
methods for locating different types of PL/I variables in a memory dump are 
described and illustrated. The section is: 


XII11l Debugging PL/! Programs 
Next, a series of hints on the effective use of PL/I are given. Methods’ for 
optimizing PL/I programs are suggested and some common programming errors 


illustrated. The sections are: 


XIV Efficiency Considerations 
XV Common Programming Errors 


Finally, a sample problem is programmed in PL/! in two ways. The first program 
illustrates how a programmer can use PL/I to solve a problem quickly for his own 
use. The second program illustrates the use of PL/I for the development of a 
routine for a production environment. The section is: 


¥Vi Soldtion of a Problem in Pt/t 
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In addition to these sections, appendixes are included in the User's Guide to 
give reference material in tabular form. The appendixes are: 


Restrictions in Series 60 PL/I 

Comparison of Series 60 PL/I and Standard PL/I 
Memory Limits 

Character Conversion Tables 

Internal Representation of PL/I Data Tyes 
External Names. 

Format of the INCLUDE File 

Error Messages 

ON Codes 
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Related Manuals 


Additional information on the PL/I language and the Series 60 is available. 
The PL/I language is described in another Honeywell publication, as follows: 


The PL/I Reference Manual (Order Number DE05) describes the Series 60 
PL/1 language. Each feature of the language is explained by an 
example, and the rules of the language are given in definitions that 
are informal but complete. 


The aspects of the Series 60 environment discussed in this manual are described 
in other Honeywell publications, as follows: 


The Gener Comprehensive Operati Supervisor COS manual (Order 
Number DD19) describes the functions of GCOS. 


The Control Cards Reference Manual (Order Number DD31) describes’ the 


control cards used in the execution of the activities of a job. 


The General Loader manual (Order Number DD10) describes’ the 
general-purpose loader used to initiate an execution activity. 


The File and Record Control manual (Order Number DDO7) describes file 
processing. 


The Indexed Sequential Processor manual (Order Number DD38) describes 


the processor used for creating, accessing, and maintaining files with 
indexed sequential organization. 


GCOS FUNCTIONS 


The General Comprehensive Operating Supervisor (GCOS) consists of a set of 
control programs and processing programs that monitor the current status of all 
system resources and jobs in the system and allocate optimum resources to each 
job. 


GCOS performs the following functions: 


Input media conversion 
Resource allocation 
Execution 

Termination 

Output media conversion 
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Each of these functions is considered in the following paragraphs. 


Input media conversion handles input data in two categories: system related 
data and program data. The system related data consists of control cards that 
define peripheral devices, processors, and storage requirements’ for the 
activities belonging to a job. The program data consists of the information to 
be processed by the program. 


Resource allocation is based on the information obtained from the control 
cards. If the resources required for a job activity are not currently available 
in the system, the job activity is suspended. 


Execution of the activity under the supervision of a dispatcher begins when 
all the necessary resources are secured. The dispatcher queues activities with 
an attached priority and processes activities from the queue in the order of 
their priorities. 


Termination follows the completion of a job activity. Errors and 
accounting information about the job activity are written on the SYSOUT file, 
the file is closed, and all eresources allocated to the job activity are 
released. 


Output media conversion takes place when all the activities that constitute 
a job are processed sequentially through allocation, execution, and termination. 


Comp i] ion of PL/I Programs 


The compilation of a PL/I program requires the execution of a large system 
program, namely the PL/I compiler. GCOS loads the PL/I compiler from a 
catalogued master file, allocates the necessary resources for the compiler, and 
passes control to the compiler. The compiler then accepts a PL/I source program 
and translates it to an object program if no uncorrectable errors are found. 


Note that PL/I source programs must be prepared using either the BCD or 
ASCI! character set. Section XV discusses special character considerations and 
Appendix D ists the graphic and punch-card representations of these character 
sets. 


The PL/!I compiler can be used to perform a simple syntactic check of a 
source program, to compile a source program, or to compile and optimize a source 
program. The amount of processing done by the compiler is specified by the use 
of options. The structure of the compiler and the compiler-directing options 
are described later, in the section on the "Compiler". 
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The compiler operates in batch processing mode. The size of the source 
program determines the amount of memory that is required. Approximately 80K is 
needed for the compilation of a small PL/I program and 100K for an average 
program. 
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="Toadin nd Execution of PL/I Programs 


The execution of a PL/I program requires the loading of that program and 
the necessary subroutine group. The object program, the called subroutines, and 
the run-time packages are linked and the object program is executed. 
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SECTION 11 
EXECUTION OF A PL/I PROGRAM 
This section describes the control cards that are used to compile and 
execute a PL/I program. These control cards define the compilation parameters, 


loading and execution operations, peripheral device assignments and core storage 
requirements. 


DECK SETUP 


An example of a basic control card setup that compiles and executes a PL/I 


external procedure follows. In this example, the source program is on cards. 
1 8 16 
$ SNUMB 12345 
$ IDENT LETA, 4225545 10P2 
$ OPTION PL1 
$ PL1 LLSh 
‘ PL/I Source Program 
$ EXECUTE 
$ LIMITS 2, 30K, ~&K 
$ ENDJOB 
*** EOF 
CONTROL CARDS 


A detailed description of the control cards is given in the Control Cards 
Reference Manual. A brief description for each card in the example is’ given 
here. 


SNUMB Control Card 


The $ SNUMB control card provides an identifying name for the job. The 
format of the $ SNUMB card is: 


1 8 16 
$ SNUMB identifier 
where: identifier is a l- to 5-character alphanumeric 


name identifying the job. 
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IDENT Control rd 


The $ IDENT control card supplies the account number for the job and_ the 
name of the user. The format of the $ IDENT card is: : 


1 8 16 


$ IDENT account-no, name 
where: account-no is the account number 


name is a l- to 12-character name 
identifying the user. 


OPTION Control Card 


The $ OPTION control card sets all the options required for loading a 
program. This card is described later, in the section on the "| oader™ . 


PL1 Control Card 


The $ PL1 control card specifies the compilation activity. Options’ that 
direct the compilation can be given on this card. The format of the $ PLI 
control card and the options that can be requested are described later, in the 
section on the "Compiler". 


EXECUTE Control Card 


The $ EXECUTE control card specifies the activity of loading and executing 
the program produced as a result of the compilation activity. In response to 
this card, the loader brings the program into memory and_ links library 
subroutines to the object program. Normal termination of the loading initiates 
the execution of the object program. Further discussion of the $ EXECUTE 
control card is given later, in the section on the "Loader". 


LIMITS Contro rd 


The $ LIMITS control card modifies standard activity resource limits. The 
format of the $ LIMITS card its: 


1 8 16 : 
$ LIMITS time,storage-1,storage-2,print-lines, 1/O-time 
where: time is a decimal integer that specifies the maximum 
processor run-time for the activity in hundredths 
of an hour. 
storage-l is a decimal integer followed by "K'" that specifies 


the number of 1024 word blocks requested by a slave 
program that can be shared with the loader. 
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storage-2 is a decimal integer, followed by '"K' and preceded 
by a minus sign, that specifies the number of 
1024-word blocks to be added to the size of the 
General Loader to allow extra space for load tables. 


print-lines is a decimal integer that specifies the maximum 
number of print lines to be written on SYSPRINT. 


|/O-time is a decimal integer that specifies the maximum 
amount of 1/0 time in hundredths of an hour. 


The $ LIMITS card is not required for PL/I compilation since’ the following 
standard limits are defined: 


Time Storage-1 Storage-2 Print-lines 1/0-time 
215 90K 0 12000 None 


JOB Control] Card 


The $ ENDJOB control card indicates the end of the job. The format of the 
¢ ENDJOB card is: 


1 8 16 


$ ENDJOB 
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SECTION III 


SYSTEM INPUT/OUTPUT FILES 


The file handling capability of PL/I is general and flexible. Four types 
of file organization can be generated and accessed by PL/I programs, namely: 


CONSECUTIVE 
INDEXED 
REGIONAL 
INTERACTIVE 


The basic concepts of file handling are described later, in the section on 
"External Files". The section on "External Files" is followed by three sections 
that give the details of file attachment and use. 


A large number of PL/I programs, however, use only the system input/output 
files. Since knowledge of the general capability is not required for the use of 
the system input/output files, a brief description of these files is given in 
this section. 


SYSTEM INPUTZOUTPUT File Use 


The two system files are SYSIN, the system input file, and SYSPRINT, the 
system output file. These files need not be declared, opened, or closed. If 
the filename is omitted from a GET statement, the filename SYSIN is assumed; _ if 
the filename is omitted from a PUT statement, the filename SYSPRINT is assumed. 


The system input/output files have the following description: 


Filenam Attribute Record Size 
SYSIN INPUT,STREAM 80 characters 
SYSPRINT OUTPUT,STREAM, PRINT 132 characters 


S m Input/Output File Codes 


Files referenced in a PL/I program are attached to external files by a file 
code. The general rules for determining and using file codes are given later, 
in the section on "External Files''. The file codes for the system input/output 
files are as follows: 


Filename Filecode 
SYSIN | * 
SYSPRINT Px 
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To provide a program with input data on the system input file, the file code I|* 
is used, 


System Input 


The data for a PL/I program can be included in the deck that contains’ the 
control cards and program cards. To include the data, a $ DATA control card is 
used. The $ DATA control card writes files onto a temporary linked disk for 
input to a user activity. The $ DATA control card has the following format: 


1 8 16 

$ DATA fc,options 

where: ré is the 2-character code identifying the file. 
options are described in the Control Cards Reference 


Manual. 


Deck Setup Including Program Data 


When the input data for a program is included in the job deck, the deck 
setup of the previous section is modified to include a $ DATA control card, as 
follows: 


i 8 16 
$ SNUMB 12345 
$ IDENT TETAS ALLO Spe lLUrS 
$ OPTION PL1 
$ PL1 
; PL/!| Source Program 
$ EXECUTE 
$ LIMITS 2, 30K, "4K 
$ DATA |* 
‘ Program Data 
$ ENDJOB 
*** EOF 


EXAMPLE OF THE USE OF T SYSTEM INPUT/OUTPUT FILES 


The use of the system input/output files is illustrated in the program 
given in Figure 3-1. The program determines the largest and smallest items from 
a list of five items. The list of five items is read from the system input file 
and the minimum and maximum values are printed on the system output file. 
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$ 
$ 
$ OPTION Pit 
$ 


EXAMPLE: PROC OPTIONS(MAIN) ; 


DCL (N1, N2, N3, N4&, N5, SMALL, LARGE) FIXED BIN; 
DCL (MIN, MAX) BUILTIN; 


ON ENDFILE (SYSIN) GOTO EXIT; 


LOOP: GET LIST (N11, N2, N3, N&, NS); 
SMALL = MIN(N1, N2, N3, N&, N5); 
LARGE = MAX(N1, N2, N3, N4&, N5); 
PUT LIST (SMALL, BARGE? SKIP; 


GOTO LOOP; 
EXIT: END; 
$ EXECUTE 
$ LIMITS: 2,30K,—2K 
$ DATA | * 
a a ae ae 
2G 3 6 


50 60.20 10 30 

a15 «20° =35° 5 -=10 
$ ENDJOB 
*k*kKkEOF 


Figure 3-1. The Use of Standard Files 


The compiler output listing obtained from the execution of the program of Figure 
3-1 is reproduced in the next section of this manual to illustrate the different 
sections of an output listing. 


The output from the program of Figure 3-1 follows the compiler output 
listing on the standard output file, as follows: 


SNUMB = 7605T, ACTIVITY # = 02 REPORT CODE RECORD COUNT = 000005 
1 6 | 
2 g 
10 80 
eee 5 
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SECTION IV 
COMPILER 
This section describes the PL/I compiler, the files used by the compiler, 


the options that can be specified to adjust the behavior of the compiler, and 
the output listing produced by the compiler. 


COMPILER PHASES 


A PL/I! source program is translated into an executable object program by 
the PL/I compiler in six phases. During these phases the compiler produces 
edited error messages or object programs, as required. The six phases are: 


Description Phase Name 
Compiler control phase ' COMMON 

Syntax analysis phase > PARSE 

Semantic analysis phase > SEMANT 
Optimization phase “/ OPTIMIZER 

Code generation phase >? CODE GENERATION 
Error message editing phase / DIAGNOSTIC 


~ 


The programmer can determine the phases of the compiler that operate on his 
program by specifying options on the $ PL1 control card. The PARSE option 
directs the compiler to perform only the syntactic analysis phase; the CHECK 
option directs the compiler to perform only the syntactic and semantic analysis 
phases; and the OPTZ option directs the compiler to perform an optimization 
phase in addition to the usual phases of the compiler. The SEVERITY option 
directs the compiler to suppress error messages with level number less than the 
integer argument given with the option. A detailed description of the options 
recognized by the PL/I compiler is given later in this section. 


The logical flow of the PL/I compiler is illustrated in Figure 4-1. If no 
options are specified, flow proceeds along the path straight down from the PARSE 
phase to the DIAGNOSTIC phase. 
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Figure 4-1. Logical Flow of the PL/I Compiler 
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Compiler Control Phase (COMMON) 


The compiler control phase is in main storage throughout the compilation of 
a a source program. This phase controls the execution of the other phases’ and 
performs the following actions: 


Establish GCOS interfaces 
Interpret compiler options 
Determine overlay structure 
Prepare output list 

Determine storage space allocation 
Prepare diagnostic message output 
Prepare other services 


syntax Analysis Phase (PARSE) 


The syntax analysis phase consists of two parts: 


Lexical analysis 
Parse 


During lexical analysis, the compiler constructs a series of tokens to represent 
source language statements. During parse, the token string created by lexical 
analysis is used to create for the program a tree structure that represents the 
relationships that exist among the elements of the source program. 


semantic Analysis Phase (SEMANT) 


~ The semantic analysis phase handles declaration and semantic conversion. 
| The declaration process allocates storage for variables appearing in the 
program. The semantic conversion process analyzes the tree structure 


representing the source program and facilitates operator conversion and operand 
processing. 


Optimization Phase (OPTIMIZER) 


The optimization phase is an optional phase that can be requested by 
specifying the OPTZ option on the $.PL1 control card. The PL/I compiler 
produces reasonably efficient code without this phase. Two major optimizations 
are performed in this phase, namely: 


Factoring of common sub-expressions 
Moving invariant computations outside loops 


This phase is usually requested for the final compilation of a-= production 
program. 


‘> DEO4 


od ration Phas CODE GENERATION 


Two functions are performed by the code generation phase: 


Allocation of storage space 
Generation of the object code 


The object code is the series of machine instructions generated from the tree 
representation of the program. 


Error Mess Pai ti Phas 1AGNOSTIC 


The error message editing phase produces edited error messages describing 
the errors detected in the compilation of the source program. At the completion 
of this phase, control returns to the compiler control phase and the compilation 
is completed. | ? 


FILES USED DURING COMPILATION 


The PL/|I compiler uses standard system files, implicitly generated by GCOS. 
The files used in a PL/I compilation are given in Table 4-l. The relationship 
of these files to the compiler is shown in Figure 4-2. Each file is then 
described in more detail. 


Table 4-1. Files Used in a PL/I Compilation 


File 
Code File Name Size Type 


Alter file variable linked 


Object program file 2 links linked 
Object deck file 
Stranger option file 
Compressed deck file 


System output file 


Source program file variable linked 


Work file 5 links random 


Include file? 


if an include file is used, it must be prepared 


by the user. 
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S* D* Ax mE 
Source Stranger Alter INCLUDE 
a Program File Option File File Macro File 
*3 


Pou ie oS eee | 
Compiler File 


Px 


ALTNO a Alter ca 
Listing 


Option 
Listing 
Source Program 
Listing 


C* 
Kx | 
Compressed COMDK SYMT Symbol Table 
Deck Listing 
Bx 


Object DECK 
Deck LSTIUN 


LSTIN 


XREF | Cross-Reference 
A 
MAP | Object Map 
Listing 
Object $ EXECUTE | 
Program LSTOU | (Object Program 
| Listing 
LSTIN | 
SEVERTTYN Error Message 
e Listing : 
Figure 4-2. Files Used During Compilation 
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The alter file (A*) is used to make partial modification of the PL/I source 
program to be compiled. A detailed description of the modification of a source 
program using $ ALTER cards is given in the File and Record Control manual. 


The alter file is generated by the GCOS system input module when a $ UPDATE 
card is detected. The $ ALTER and source program cards are stored in the alter 
file by the system input module. 


Object Program File 


The object program file (B*) is used to store the object program generated 
as a result of the compilation of the source program by the PL/I compiler. 


The object program file is generated by ALLOC, a GCOS module, when a 
$ EXECUTE card occurs tin the job. 


Obiect Deck File 


The object deck file (C*) contains the deck generated by the PL/I compiler. 
The object deck begins with the $ OBJECT card and ends with $ DKEND card. 


The object deck file is generated by ALLOC, a GCOS module, when the _ DECK 
option is given on the $ PL1 control card. 


Stranger Option File 


The stranger option file (D*) contains card images of options specific to 
the PL/I compiler given on the $ PL1 control card. The PL/I compiler interprets 
the options given in this file. 


The stranger option file is generated by the GCOS system input module when 
options that have no commonality with other language processors are given on the 
> PLL e¢ontro| card, 


Compressed Deck File 


The compressed deck file (K*) contains the source program in a compressed 
form. A detailed description of a compressed deck is given in the File and 
Record Control manual. 


The compressed deck file is generated by ALLOC when the COMDK option is 
given on the $ PL1 control card. The compressed deck is stored in the format of 
an input file to the PL/I compiler and can be used aS a source program input 
(S*) e 
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S m Output Fi] 


The system output file (P*) is used when the PL/I compiler, or any. other 
processing program under GCOS, outputs reports or processing results. This file 
is usually allocated to the system output device and is fed to this device via 
SYSOUT, a GCOS module. 


The maximum number of lines that SYSOUT can output. for one activity ts 
530,000. Output beyond this limit can also be fed to the line printer by first 
allocating the system output file to a magnetic file or disk and _ then 
transferring its contents to the line printer by the Bulk Media Conversion (BMC) 
module. 


Listings that the PL/1 compiler outputs on the system output file (P*) are 
described and and illustrated later in this section. 


The system output file is generated by ALLOC when processing results. are 
output. 


Source Program File 


The source program file (S*) contains the PL/I source program image used as 
input for the compilation. 


The source program file is generated by the system input module when source 
cards are present in the job stream. The source program file (S*) may also be 
provided by a $ PRMFL card. 


Work File 


The work file (*3) is used to store intermediate results. 


The work file is generated by ALLOC. 


INCLUDE File 


The INCLUDE file is prepared by the user as a file to store macro text when 
the ZINCLUDE statement is used in the PL/|I program. Appendix G gives a detailed 
description of INCLUDE files. 


OPTIONS 


By the use of options the programmer can direct the compiler in the 
translation of his program. For example, options can be requested that limit or 
extend the amount of processing done by the compiler, that request additional 
output listings, that change the form of input and output, and that suppress a 
class of error messages. 
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An option can be requested, negated, or omitted. An option is requested by 
giving the option name on the appropriate control card; for example, to request 
optimization the programmer specifies OPTZ. An option is negated by specifying 
the option name prefixed with the letter 'N'; for example, to negate the option 
OPTZ, the programmer specifies NOPTZ on the appropriate control card. it con 
option is omitted, a default assumption is made about the specification of the 
option. 


There are two types of options, standard options and special options. The 
option names and the method of specifying options are given for both types in 


the following paragraphs. 


Standard Options 


The standard options allow a programmer to determine which phases of the 
compiler operate on his program and to specify the listings and decks produced 
by the compilation. 


Standard options are specified on the $ PL1 control card. For example, the 
following $ PL1 control card illustrates the specification of the standard 
options ALTNO and COMDK. ) 


1 8 16 


$ Plt ALTNO,COMDK 


A detailed description of the control card formats used to specify the standard 
options is given later in this section. 


The standard options recognized for the PL/I compiler are given in Table 
h-2, A brief description of the meaning and the associated default assumption 
is given for each option. Following the table, a more detailed description is 
given for each of the options. 
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Table 4-2. Standard Options 


ALTNO Produce a list of the source program with NO ALTNO 
alter numbers, 


NO 


Suspend the code generation phase. CHECK 


Produce a compressed deck of the source NO 


program, 


COMDK 


Include in the symbol table the internal NO 


names created by the compiler. 


CSYM 


NO DECK 


Produce a binary deck for the object 
program, 


Assume that LSTOU, MAP, SYMT, and XREF 
are specified. 


NO 


ee oj 


LSTIN 


Produce the option list, expanded source 
program, storage requirements, external 
symbols, and compiler storage requirements. 


Produce a list of the object program. NO LSTOU 


NO MAP 


Produce a map that associates the line 
numbers of the source program with the 
relative address in the object program. 


NLSTIN 


Cancel the LSTIN option. LSTIN 


Optimize the object program. NO OPTZ 


OPTZ 


PARSE Suspend semantic analysis and code NO PARSE 


generation. 


SEVERITYn Suppress error messages with a severity SEVERITY1 


level less than the indicated number. 


NO SNUMBER 


Attach the line number of the source 
program to error messages. 


NO STAB 


Generate a complete symbol table that 
can be used at execution time. 


Produce a list of names used in the NO SYMT 


source program and their attributes. 


Produce a cross reference table with the NO XREF 
symbol table indicating lines of 


declaration and reference for each name. 
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STANDARD OPTION NAMES 


The standard options recognized by the PL/! compiler are described in the 
following paragraphs. 


ALTNO Option 


The ALTNO option directs the compiler to produce a lGPsting of . tae... source 
program with attached alter numbers. The source program listing is an exact 
copy of the source program input to the compiler and contains star (*) option 
cards and %INCLUDE statements. This listing is useful for determining the line 
number in the program for altering the output compressed deck image, especially 
if the program contains the ZINCLUDE statement or if the LONGFORM option is also 
requested. 


CHECK .Option 


The CHECK option causes the compiler to suppress the code generation phase. 
Syntax analysis and semantic analysis are performed and any errors detected 
during these phases are reported. 


The use of this option allows the programmer to save computer time during 
the initial compilations of his program when the probability of errors is high. 


COMDK Option 


The COMDK option directs the compiler to produce a compressed deck of the 
source program. Columns 73 through 76 of this deck contain the name of the 
deck, composed of four characters specified by the TITLE option or as described 
below. Columns 77 through 80 contain a sequence number. 


CSYM Option 


The CSYM option directs the compiler to add the internal names created by 
the compiler to the symbol table output listing. The attributes of each 
internal name are given in the listing. The CSYM option is recognized only when 
the SYMT option is also requested. 


DECK Option 


The DECK option directs the compiler’ to produce a binary deck for the 
object program. 


LIST Option 


The LIST option directs the compiler to proceed as if the LSTOU, MAP, SYMT, 
and XREF were requested. The LIST option is a convenient way to obtain a 
complete output listing. 
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LSTIN Option 


The LSTIN option directs the compiler to produce the option listing, the 
expanded source program listing, the storage space and external symbol listing, 
and the storage capacity required at compile time. These listings are parts of 
the compiler output listing described and illustrated later in this section. 


The LSTIN option is the only option with a positive default assumption. 
Therefore, if no options are specified, the output requested by the LSTIN option 
is produced. 


LSTOU Option 


The LSTOU option directs the compiler to produce a listing of the object 
program in the compiler listing. The object program is given in a_ format 
similar to that of assembly language. 


The object program listing is described and illustrated later in this 
section. 


MAP Option 


The MAP option directs the compiler to produce the table that gives’ the 
association between the line number of the source program and the relative 
address of the generated object code for that line of source language. 


The object program map listing is described and illustrated later in this 
section. 


OPTZ Option 


The OPTZ option directs the compiler to perform an additional optimization 
phase. In this additional phase, common sub-expressions are eliminated. The 
code produced by the compiler, without this additional phase, is quite 
efficient. The decision to request the OPTZ option is based on considerations 
of program size and frequency of execution. 


PARSE Option 


The PARSE option directs the compiler to suppress the semantic analysis and 
code generation phases. This option is useful for the initial compilations of 
programs that use the ZINCLUDE statement in which syntactic errors can be 
especially serious. 


SEVERITY Option 


The SEVERITY option, with its associated integer 'n', directs the compiler 
to suppress the listing of any error messages with level number less than 'n'. 
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Error levels for PL/I error messages range from tevel 1 (warning ievei) to 
level & (fatal error). The error levels are categorized, as follows: 


Level Meaning 
1 Warning. The program contains a construction that may be_ in 
error. The compilation is not affected by an error of level 
Lx 
2 Correctable error. Errors of level 2 are corrected by the 


compiler and the compilation process continues unless the 
correction affects the process adversely. 


3 Uncorrectable error. Errors of level 3 are not fatal, but 
cannot be corrected. The compilation process continues from 
the next logical point in the program, but code generation is 
suspended. 


4 Fatal error. Errors of level 4& cause compiler termination. 


For example, the option SEVERITY2 causes warnings (level 1) to be 
suppressed but allows error messages with a level greater than or equal to 2 to 
be listed. 


SNUMBER Option 


The SNUMBER option directs the compiler to include the corresponding source 
program statement number and line number in the information given by the error 
trace-back when an error occurs at execution time. 


STAB Option 


The STAB option directs the compiler to generate a complete symbol table 
for use at execution. time. Variable names, label names, and entry names 
referred to in the source program are arranged so that execution time debugging 
can be performed conveniently. 


SYMT Option 


The SYMT option directs the compiler to produce the symbol table listing as 
part of the compiler output listing. The symbol table listing contains the 
names used in the source program with their attributes. The symbol table 
listing is described and illustrated later in this section. 


XREF Option 


The XREF option directs the compiler to include in the symbol table listing 
the line numbers on which each name is declared and referenced. The XREF option 
implies the SYMT option and automatically specifies it. 


= 
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STANDARD OPTION CONTROL CARDS 


Standard options are given on the $ PL1 control card, in the following way: 


8 16 7 8 0 
$ PL1 Optton, opt.ion;..% (not used) 
The options are separated by commas and can be given in any. order. A control 
card is terminated by a blank column, so no imbedded blanks can be included in 
the option list. If the last nonblank character on the card is a comma, more 
options are assumed to follow. The additional options are given ona $¢ ETC 
control card, as follows: 
a 8 16 73 80 
$ PL1 option,option, (not used) 
$ ETC Opt iOhs<..< (not used) 


The format of the $ ETC control card is similar to that of the $ PL1 control 
card. If the $ ETC control card ends with a comma, another $ ETC control card 
is assumed to follow. 


Each option name must be entirely contained on one control card and cannot 
be continued from one card to another. 


The following example requests the options DECK, MAP, LSTOU, and SYMT on a 
single $ PL1 control card: 
$ Pid DECK,MAP,LSTOU, SYMT 


The same request can be made on several cards, as follows: 


$ PL1 DECK, 

$ ETC MAP,LSTOU, 

$ ETC SYMT 
Special Options 


The special options are used to name a program, to determine conventions 
for different versions of PL/I, to request statistical information about the 
compilation process, and to change the format of output listings. 


Special options are given on star (*) control cards and are interpreted by 
the PL/I compiler. For example, the following star (*) control cards assign the 
name PRG1 to any output program decks, provide a listing title and request the 
special option SMESSAGE. 


i! 13 69 
*TETLE ALPHA PROGRAM MAIN LISTING PRG1 
*OPTIONS SMESSAGE 


A detailed description of the control card formats used to specify the special 
options is given later in this section. 
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The special options recognized by the PL/I compiler on the *OPTIONS cards 
are given in Table 4-3 with a brief description of their meanings. Fol lowing 
the table, a more detailed description is given for each option. 


Table 4-3. Special Options 


Regard scaled arithmetic fixed-point 
constants as arithmetic floating- 
point constants. 


FLOATBIN 


| BMFORM 


Process source in columns 2 - 72 only. 


LONGFORM Interpret the character '#' or "@" in 


column 1 as the continuation symbol. 


SEC_SYMDEF Create for each external entry name 
containing a '$' character a 
corresponding entry name to be used as 


a secondary symbol. 


SHORT_CALL 


Reduce the size of the object program 
by restricting the code generated for 
subroutine calling sequences. 


SMESSAGE 


Do not use the full printer for error 
message output. Limit it to 80 columns. 


STATUS Produce statistical data about the 


compilation. 


SPECIAL OPTION NAMES 


The special option names recognized by the PL/I compiler are described in 
this section. 


FLOATBIN Option 


The FLOATBIN option directs the compiler to regard any scaled arithmetic 
fixed-point constant in the source program as an arithmetic floating-point 
constant. 


This option is provided so that programs written in the IBM DOS PL/I 
language can be compiled by the PL/I compiler. 
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IBMFORM Option 


The IBMFORM option directs the compiler to process data in columns 2 
through 72 of the input card. Column 1 and columns 73 through 80 are not 
Processed when this option is requested. If this option is not requested, the 
entire card is processed. 


LONGFORM Option 


The LONGFORM option directs the compiler to interpret the character '#! or 
"@" in column 1 of the source Program ftnput card as a_ symbol indicating the 
continuation of output lines in the source program listing produced by the 
compiler. 


Since the image of each input card with this continuation symbol is’ the 
logical continuation of the Preceding card, the compiler tries, insofar as 
possible, to put the complete image on a single line in the program listing. 


This option is provided to allow. the Programmer to produce a_=e program 
listing that is easy to read and to understand. 


SEC_SYMDEF Option 


The SEC_SYMDEF option directs the compiler to create a corresponding entry 
name to be used as a secondary Symbol for each external entry name that contains 
a '$' character. 


The loader processing of the secondary SYMDEF occurs after the processing 
of the primary SYMDEF, The General Loader manual contains a complete 
description of this processing. 


SHORT_CALL Option 


The SHORT_CALL option directs the compiler to reduce the size of the object 
program by restricting the code generated for subroutine calling sequences. The 
object programs created when this option is specified are smaller in size but 
execute less efficiently than programs created when the option is not requested 
Or is negated, 


SMESSAGE Option 


The SMESSAGE option directs the compiler to use only 80 columns of the 
Printer line for the listing of error messages. This option is used to limit 
page width. 
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STATUS Option 


The STATUS option directs the compiler to produce statistical data about 
the compilation of the source program in the compiler listing. 


The compiling statistic list, produced as a result of requesting this 
option, is described and illustrated later in this section. 


SPECIAL OPTION CONTROL CARDS 


Special options are given on one or more star (*) control cards. The star 
control card is a PL/I control card and contains options that are specific to 
the PL/I compiler. The star control cards must be given first in the -PL/I 
source program input deck. 


The TITLE option card must be the first card if it is present. Its format 


1 13 6 i 8 0 
TE GLe Listing heading of user's choice YYMMDDXXXX(C not used) 


The listing heading replaces the standard main title line of _ the compilation 
listings. The date is optional and the date of compilation is entered if 
columns 63-68 are blank. The date is placed in columns 67-72 of the $ OBJECT 
card of the object deck (if any). Columns 69-72 of the *TITLE card are used for 
identification of output object and compressed source decks if such decks are 
requested by the appropriate options. The first 32 characters of the title are 
reproduced on the $ OBJECT card of the object deck (if any) beginning at column 
16. If no TITLE card is present, the deck identification is four zero 
characters and blanks are entered on the $ OBJECT card. 


The SUBTITLE option card must be the second card if it is present. The 
format is: 


13 80 


1 13 


*«SUBTITLE Listing subheading (not used) 


Columns 13-72 become the subtitle on the compilation listing. If there is no 
SUBTITLE card the subtitle consists of the standard subtitle line that includes 
the first text line image of the program. 


The COPYRIGHT option card has the following format: 
1 13 73 80 
*COPYRIGHT "any desired copyright message" (not used) 


The given message will be printed in a box formed with asterisks on the option 
listing page of the compiler output listing. A typical message could be 


"COPYRIGHT 1975 BY THE ABC WIDGET CO." 
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The format of the OPTIONS option card is as follows: 


1 13 13 80 
*OPTIONS Options <<. (not used) 


The special options given in Table 4-3 are separated by commas and can be given 
In any order. More than one *OPTIONS card may be present. 


Example of the Use of Options 


The following program fragment illustrates the use of both Standard and 
special options: 


1 8 L3 16 69 
$ SNUMB L255 
$ IDENT ZETA,X22353,STOP2 
$ OPTION Pik 
$ PL1 DECK,COMDK,LIST, 
$ ETC ALTNO 
*TITLE PROGI1 PRGA 
*OPTIONS SMESSAGE, STATUS 
‘ PL/I Source Program 
$ EXECUTE 
$ LIMITS 2,30K,-4K 
$ ENDJOB 
**x* EOF 


The standard options DECK, COMDK, LIST, and ALTNO and the special options 
SMESSAGE and STATUS are requested. 


COMPILER OUTPUT LISTING 


The compiler output listing is divided into sections. Each section is a 
listing that gives information about the source program, the compilation, or the 
object program. The programmer can select the sections of the listing to be 
produced by specifying options. The sections are shown in Table 4-4 in the 
order in which they appear, if requested, in the output listing. Associated 
with each section in the table is the option whose specification causes that 
section of the listing to be produced. 


Following the table, each section of the listing is described and 
illustrated. The program EXAMPLE, given in Figure 3-1, was used to produce the 
sample listings included here. 
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Table 4-4, 


Alter listing 

Compiler option listing 
Expanded source program listing 
Symbol table 


Cross reference table 


Storage space and external 
symbol listing 


Object program map 


Object program listing 


Error message listing 
Compiling statistics listing 


Storage capacity required 
at compile time 


Alter Listing 


The alter listing 


This listing is used to change the compressed deck of the source 
numbers associated with the lines of the source program 


Sections of the Compiler Output Listing 


ALTNO 
LSTIN 
LSTIN 
SYMT 
XREF 
LSTIN 


MAP 

LSTOU 
SEVERITYn 
STATUS 


LSTIN 


is a listing of the source program with alter numbers. 


program. The 
in the alter listing can 


be different from the line numbers in the expanded source program listing due to 
the presence of star (*) option cards and the ZINCLUDE statement. 


The alter listing for 


the sample program EXAMPLE follows. 


This listing 


shows that the special option STATUS was given ona star (*) control card. 


ALTER NO SOURCE 
*OPTIONS 
EXAMPLE: 
DCL (N1, N2, N3, N&, 
DCL (MIN, 


STATUS 


1 

2 

3 

k 

5 

6 LOOP: GET LIST(N1, N2, N3, 
7 SMALL = MIN(NI, N2, 
8 LARGE = MAX(NI1, N2, 
9 PUT LISTCSMALL, 
10 GOTO LOOP; 
Li EXIT = END: 


IMAGE OF THIS PROGRAM 


PROC OPTIONS(MAIN); 

N5, SMALL, 
MAX) BUILTIN; 

ON ENDFILECSYSIN) GOTO EXIT; 
N4, N5); 
N3, 


LARGE) FIXED BIN; 


N4, N5);3 
Nu, N5); 


LARGE) SKIP; 
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Compiler Option Listing 


The complete set of standard option specifications is given in this 
listing. Options that are not specified on control cards are assumed to have 
the default interpretation described earlier in this section. 


Any special options given on ae star (*) control card are listed. The 
complete set of special options, however, is only included in the listing when 
the STATUS option is requested. 


The compiler option listing produced as a result of a job that requested 
the standard options ALTNO, COMDK, CSYM, and DECK and the special option STATUS 
is given below. 


OPTIONS USED IN THIS COMPILATION 
*OPTIONS STATUS 


COMPLETE LIST OF OPTIONS 

LSTIN 

NO LIST 

NO MAP 

NO SYMT 

NO LSTOU 
ALTNO 
CSYM 

NO PARSE 

NO CHECK 

NO OPTZ 

NO SEVERITY 

NO STAB 
DECK 
COMDK 

NO SNUMBER 

NO XREF 
STATUS 

NO SHORT_CALL 

NO LONGFORM 

NO |!BMFORM 

NO SEC_SYMDEF 

NO FLOATBIN 


Expanded Source Program Listing 


The expanded source program listing gives a numbered list of the source 
program. If a ZINCLUDE statement is present, it is replaced in this listing by 
the expanded image. The nesting level of the DO group is given on each line, 
following the line number. 


If the LONGFORM option is requested, the expanded source program listing 
occupies columns 9 - 136. 
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The expanded source program listing for the sample program EXAMPLE is given 
below. Notice that the line numbers differ from the line numbers in the alter 
listing given earlier in this section due to the _ presence of the ‘star <*2 
control card. 


COMPILATION LISTING OF PROGRAM: EXAMPLE: PROC OPTIONS(MAIN); 


EXAMPLE: PROC OPTIONS(MAIN); 
DCL (N1, N2, N3, N4&, N5, SMALL, LARGE) FIXED BIN; 
DCL (MIN, MAX) BUILTIN; 
ON ENDFILE(SYSIN) GOTO EXIT; 
LOOP: GET LIST(N1, N2, N3, N&, N5); 
SMALL = MIN(N1, N2, N3, N4&, N5); 
LARGE = MAX(N1, N2, N3, N4&, N5); 
PUT LIST(SMALL, LARGE) SKIP; 
GOTO LOOP; 
EXIT? END; 
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The symbol table listing is a list of names declared or used in the source 
program. The names are given in the following order in the table: 


8 Names declared explicitly by the DECLARE statement. 
s Names declared but not used. 
a Names declared explicitly through context outside of the DECLARE 


statement. (For example, label constants, format constants, and entry 
constants. ) 


# Names declared implicitly or by context. 


For each name, the following information is listed: 


* If the name is that of a structure member, its structure’ relative 
address is given in the form of a word offset (in octal) and bit 
offset (in decimal). 


e Address. 
F Storage space attributes. 
& Data type attributes. 


If the XREF option is requested, the cross reference listing is produced 
for each name in the symbol table. The cross reference listing indicates the 
line numbers of the declarations and references for each name and an indication 
as to whether or not the value of the variable is set. 


References to a DEFINED variable are included in the cross reference table 
for the base variable since the storage generation for the two variables are the 
Same. The cross reference table for a pointer variable, which implicitly 
modifies (i.e., appears in the declaration of) a BASED variable, includes all 
references to the BASED variable except those using a different pointer for 
qualification. If the BASED variable has an upper bound, lower bound, or length 
specified by an expression, a simple reference to the BASED variable implies a 
reference to any variables used in the expression. 
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The symbol table and the cross reference table for the sample program 
EXAMPLE is7~ given’ here. For reproduction in this manual, the format has been 
compressed by reducing the length of each field on the listing. 


*** NAMES DECLARED IN THIS COMPILATION *** 


IDENTIFIER OFFSET LOC STORAGE CLASS DATA TYPE ATTR AND REFERENCES 
*NAMES DECLARED BY DECLARE STATEMENT* 
LARGE 000014 AUTOMATIC FIXED BIN(17,0) DCL 2 SET REF 7 8 
MAX BUILTIN FUNCTION INTERNAL DCL 3 REF 7 
MIN BUILTIN FUNCTION INTERNAL DCL 3 REF 6 
N1 000006 AUTOMATIC FIXED BIN(17,0) DCL 2 SET REF 5 6 7 
N2 000007 AUTOMATIC FIXED BIN(17,0) DCL 2 SET REF 5 6 7 
N3 000010 AUTOMATIC FIXED BIN(17,0) DCL 2 SET REF 5 6 7 
N4 000011 AUTOMATIC FIXED BIN(17,0) DCL 2 SET REF 5 6 7 
NS 000012 AUTOMATIC FIXED BIN(17,0) DCL 2 SET REF 5 6 7 
SMALL 000013 AUTOMATIC FIXED BIN(17,0) DCL 2 SET REF 6 8 
*NAMES DECLARED BY EXPLICIT CONTEXT* 
EXAMPLE 000035 CONSTANT ENTRY EXTERNAL DCL 1 REF 1 
EXIT 000167 CONSTANT LABEL DCL 10 REF 10 4& 
LOOP 000074 CONSTANT LABEL DCL 5 REF 5 9 
*NAMES DECLARED BY CONTEXT OR IMPLICATION# 
ENDFILE 000015 STACK REF CONDITION REF 4 
SYSIN 000003 CONSTANT FILE SET REF 4 5 
SYSPRINT 000004 CONSTANT FILE SET REF 8 

Storage Space and External Symbol Listing 


The storage space listing gives the amount of storage required for’ the 
object program and the automatic storage requirements. The object program size 
is given in words and includes the required storage space for INTERNAL STATIC 
variables and constants. The number of V count bits is also given. The number 
of words of automatic storage determined by the constants required for_ the 
procedure block and the automatic storage required by BEGIN blocks and ON units 
are given in this listing. 


The external symbol listing gives the external operators, external entries, 
and external variables used in the program. 
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The storage space listing and external symbol listing for the sample 
program EXAMPLE are, as follows: 


COMPILATION LISTING OF PROGRAM: EXAMPLE: PROC OPTIONS(MAIN); 


*STORAGE REQUIREMENTS FOR THIS PROGRAM* 
OBJECT PROGRAM SIZE IS 120 WORDS. (V COUNT 5) 


EXTERNAL PROCEDURE "EXAMPLE" USES 58 WORDS OF AUTOMATIC STORAGE 
ON UNIT ON LINE 4& USES 6 WORDS OF AUTOMATIC STORAGE 


*THE FOLLOWING EXTERNAL OPERATORS ARE USED BY THIS PROGRAM* 


GET LISt NEAL EXT_ENTRY ON_UNIT_ENTRY RETURN_MAC 
PUTALIST NP_AL TRA LEN TS GET_TERMINATE PUT_TERMINATE 
ENABLE_FILE GET.PREP PUTA PREP 


*NO EXTERNAL ENTRIES ARE CALLED BY THIS PROGRAM* 


*THE FOLLOWING EXTERNAL VARIABLES ARE USED BY THIS PROGRAM* 
SYSIN SYSIN# SYSPRINT | SYSPRINT# 


*EXTERNAL NAMES AND CONVERTED NAMES OF THEM* 


EXAMPLE 7EMPLE 
SYSPRINT 8SRINT 
Ob j Pro m_M 


The object program map listing is produced when the MAP option or the LIST 
option is requested. The object program map listing gives for each line of the 
source program the relative address for the start of the corresponding object 
program code. The number of words required for the object code translation of 
the source line is also given in the form of a zero-suppressed decimal number, 
truncated to 2 digits. 


The object program map for EXAMPLE is’ given here, compressed to four 
columns per line. The actual computer listing gives seven columns per line. 


*OBJECT MAP* 


CINE STZE LOG: LINE SIZE LOC LINE SIZE LOC LINE StZE 4t6C 
L. 2 -DOS032 3 000043 4 6 000055 5 5 000074 
6 14 000115 7 14 000153 8 7 000151 9 1 000166 

10 1 000167 
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Object Program Listing 


When the LSTOU option 
This listing consists of the series of assembly language 
as a result of the translation of the source program. 


The object program 


A 


INTERNAL STATIC region 
constant array 
Literal 
FORMAT 


Label 


portion 


given below: 


is requested, 


is produced 


constants 
information 
Object program procedure 


of the object program 


BEGIN PROCEDURE "EXAMPLE" 
ENTRY TO "EXAMPLE" 
105 130 101 115 000 
120 114 105 040 000 


000032 
000033 
000034 
000035 
000036 
000037 
000040 
000041 
000042 
000043 
000044 
000045 
000046 
000047 
000050 
000051 
000052 
000053 
000054 


000055 
000056 
000057 
000060 
000061 
000062 


000000 
050000 
000000 
000035 
000035 
000022 
000004 
020000 
000000 
040000 
177751 
020003 
010000 
000000 
030000 
FITTESL 
010003 


000007 
030000 
TFTI25S 
060000 
000006 
000012 


000007 

7000 00 
000072 

4500 12 
7420 12 
6200 12 
7400 12 
6200 00 
6360 10 
7560 00 
6360 O04 
7560 00 
6200 00 
6360 10 
7560 00 
6360 O04 
7560 00 


7260 07 
6200 00 
6350 O4 
7010 00 
7100 O04 
7100 O4 


000 
030 
000 
000 
000 
000 
000 
030 
000 
030 
000 
030 
030 
000 
030 
000 
030 


000 
030 
000 
030 
000 
000 


in the following order: 


instructions 


the object program listing is produced. 


produced 


listing for the sample program EXAMPLE is 


EXAM 
ree 
ZERO 
TSXBP 
ZERO 
+e 
STXSP 
EAXBP 
STXBP 
EAXBP 
EAQ 
STQ 
EAQ 
STQ 
EAXBP 
EAQ 
STQ 
EAQ 
STQ 


LXL6 
EAXBP 
EAA 
TSXLP 
TRA 
TRA 


STATEMENT 1 ON LINE 1 


0,7 


-P0090 


0,58 
29; 9°P 
29 73°P 
18,SP 
4, SP 


SYSPRINT# 


0, BP 


SYSPRINT 


a 2s FC 


SYSPRINT#+3 


SYSIN# 
0, BP 

SYSIN 
= 39 ¢ 10 


SYS (NS+3 


STATEMENT 1 ON LINE 4& 


#e:DL 
SYSIN 
-45,1C 
«FP OS76 
6, 1C 
10, 1¢ 


EXT_ENTRY 


000017 


000004 


000002 


ENABLE_FILE 


000067 
000074 
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Error M i i 


The error message listing contains the errors that are detected during the 
translation of the source program. Each error message has an associated level 
number, between one and four. A description of the error level classification 
is given in connection with the SEVERITY option earlier in this section. 


The error message list gives the error number, the severity level, the line 
number in the source listing at which the error was detected and explanatory 
text describing the error. 


The error message listing for the sample program EXAMPLE is’ given. below. 
An error of severity level 1 is printed as a WARNING. 


WARNING 75 
THE UNDECLARED IDENTIFIER "SYSPRINT' HAS BEEN CONTEXTUALLY DECLARED AS A FILE 
CONSTANT. IT WILL ACQUIRE DEFAULT ATTRIBUTES. 


WARNING 133 
THE UNDECLARED IDENTIFIER "ENDFILE' HAS BEEN CONTEXTUALLY DECLARED AS A 
CONDITION NAME. IT WILL ACQUIRE DEFAULT ATTRIBUTES. 


WARNING 75 
THE UNDECLARED IDENTIFIER "SYSIN' HAS BEEN CONTEXTUALLY DECLARED AS A FILE 
CONSTANT. IT WILL ACQUIRE DEFAULT ATTRIBUTES. 


WARNING 495 

IMPLEMENTATION RESTRICTION: LONG EXTERNAL NAME ''EXAMPLE' HAS BEEN CONVERTED TO A 
6 CHARACTER NAME. RESTRICTIONS ARE: EXTERNAL FILE NAME SIZE <= 5 AND’ OTHER 
EXTERNAL NAME SIZE <= 6. 


WARNING 495 

IMPLEMENTATION RESTRICTION: LONG EXTERNAL NAME "SYSPRINT' HAS BEEN CONVERTED TO 
A 6 CHARACTER NAME. RESTRICTIONS ARE: EXTERNAL FILE NAME SIZE <= 5 AND OTHER 
EXTERNAL NAME SIZE <= 6. 


ompili S istics Listin 


When the STATUS option is requested, the compiling statistics listing is 
produced. This listing contains statistical information about the performance 
of the compiler in the translation of the source program. 
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The compiling statistics 
symbols, statements, and core. 
program EXAMPLE is given below. 


COMPILATION LISTING OF PROGRAM: 


*STATISTICAL DATA FOR PROGRAM« 
<SUMMARY OF TOKEN USAGE> 


THE NUMBER OF TOKENS IS 59 


listing 
The compiling statistics 


THE NUMBER OF EMPTY HASH TABLE SLOT 
THE MAXIMUM NUMBER OF TOKENS IN A SLOT IS 2 


THE TOTAL NUMBER OF WORDS IS 332 


<SUMMARY OF SYMBOL USAGE> 


EXAMPLE: 


IS 160 


THE TOTAL NUMBER OF COMPILER CREATED SYMBOLS 
<SUMMARY OF NODE USAGE> 

BLOCK 4 STATEMENT 27 OPERATOR 
TOKEN 59 SYMBOL 28 CONTEXT 
MC_STATE 2 STORAGE 28 LABEL 
<SUMMARY OF STATEMENT USAGE> 

DUMMY_ST 1 ASSTGH EFC; i? END 
GOTO 2 NULL 2 ON 

PUT 2 

<SUMMARY OF CORE USAGE> 

* MAXIMUM STACK SIZE = 004651 

* SIZE FOR PGM_TREE = 001262 

* EXTENDED CORE SIZE = 000000 

Stor C i R ired at Compi] im 


[> 16 


a2 


DW 


ke RO 


summarizes the usage of tokens, 
listing for the 


PROC OPTIONS(MAIN); 


REFERENCE 
LIST 
XREF 


GET 
PROCEDURE 


nodes, 
sample 


80 


NO WN 


This section of the compiler listing consists of a single line giving the 


amount of storage required to compile the program, 


* x 66K WAS USED TO COMPILE 


For the sample program EXAMPLE, 


THIS PROGRAM. 


as follows: 


66K was required to compile the program. 
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SECTION V 


LOADER 


This section provides an introduction to the General Loader activities 
necessary for the execution of a PL/I program in the GCOS environment. The 
loader functions, loader control cards, and overlay structures are described. A 
detailed description of the loader is given in the General Loader manual. 


DESCRIPTION OF LOADER FUNCTIONS 


The General Loader produces an executable unit from a set of object 
programs, control cards, and libraries, The General Loader performs the 
following functions: 


Linkage of object programs into a single object unit 
Linkage of referenced library routines to the object unit 


Assignment of main storage space required by the program, including 
common reservations 


Definition of the overlay structure 


Creation of file control blocks for the manipulation of files required 
by the object program 


Upon completion of this processing, the loader passes control to an entry name 
within the object unit and the execution of the object programs begins. 


Oader Pro sj 


The object decks created by the PL/I compiler and other language processors 
are composed of two types of cards: preface cards and text cards. Preface cards 
contain information about the size and external names of the object program, 
The internal procedure names declared in the program (SYMDEFs), the external 
procedure names referenced in the program (SYMREFs), and the external variables 
declared and referenced in the program (Labeled Commons) are given on preface 
cards, Text cards contain the machine instructions and data for the program. 


The loader obtains input from the GCOS standard files identified by the 
file codes R* and B*,. The loader control file (R*) contains control cards and 
object programs from the input deck. The object program file (B*) contains 
object programs produced by the PL/I! compiler. The loader's primary input is 
the loader control file. When the loader encounters a § SOURCE control -card —on 
that file, it inputs the corresponding object program from the object program 
file. 
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When the object programs are loaded, the external variable procedure names 
referenced by the programs are resolved. The loader uses information contained 
on the preface cards to resolve SYMREFs, searching first any user-supplied 
libraries, then the secondary system standard library (*L), and finally the 
system standard library (L*). Every library program included in the object 
program by the PL/I compiler’ in the translation of the source program is 
contained in the standard system library. (Some installations may include them 
in the secondary system standard library.) 


Input Deck Processing 


Figure 5-1 illustrates the processing of a typical input deck by GCOS, the 
construction of the files used by the loader, and the processing of these files 
by the loader. Following the figure, the action taken by GCOS for each control 
card is described. Then, the action taken by the loader for éach. Contre: card 
on the loader control file is given. 
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SNUMB 


IDENT 
OPTION PLI 


PLi 


PL/I source A 


OBJECT 
object deck B 
DKEND 
PL1 
PL/I source C loader control file 
(R*) 


OBJECT $ OPTION PL1 
object deck D 
DKEND $ SOURCE 


PLI $ OBJECT 
object deck B 
$ DKEND 


PL/? source E 


$ LIBRARY Ul 
$ SOURCE 
$ EXECUTE 
$ PRMFL U1,R,R,USER/ LIBRARY $ OBJECT 
object deck D 
$ ENDJOB $ DKEND 
$ SOURCE 
$ LIBRARY UI 
S $ EXECUTE 
S 3 


. PL/I 
I | COMPILER 
object program 
file (Bx) 
OBJECT 
object deck A 
OBJECT 
object deck C 
| LOADER 
OBUVECT 
2 object deck E 
(*L) 


1 
secondary MAIN STORAGE 
standard SPACE 
system | 
library 


CUT) 
user- 
supplied standard 
library 


Figure 5-1. Input Deck Processing 
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GCOS 


processes the input deck and performs the following actions for the 


indicated control cards: 


Card 


$ 
$ 
$ 


HP th 


Hf HF 


The General 
during 


$ 


f HA HHA Ff Hf th 


SNUMB 
IDENT 


OPTION 


PL 


OBJECT 
DKEND 


PL1 


OBJECT 
DKEND 


Pid 


LIBRARY 


EXECUTE 


Action 


Records the information on these cards for accounting purposes. 


Copies the $ OPTION control card to the loader control file 
CRE); 


Writes a $ SOURCE card on the loader control file (R*), sets 
limits, allocates files and arranges for control to be passed 
to the PL/I compiler to translate program A. 


The PL/I compiler reads as its source program all cards up_ to 
the next control card, translates the source program A, and 
produces the object program for A on the object program file 
(Be). 


Copies the object deck B with its delimiting control cards to 
the loader control file (CR). 


Writes a $ SOURCE card on the loader control file (R*) and 
performs, for source program C, the same actions as described 
above for source program A, 


Copies the object deck D with its delimiting control cards to 
the loader control file (R*). 


Writes a $ SOURCE card on the loader control file (R*) and 
performs, for source program E, the same actions as described 
above for source programs A and C, 


Copies the $ LIBRARY card to the loader control file (R*). 


Passes control to the General Loader. 


Loader then reads the loader control file (R*) created by GCOS 


the processing of the input deck and performs the following actions for 
the indicated control cards: 


OPTION 


SOURCE 


OBJECT 
DKEND 


SOURCE 


OBJECT 
DKEND 


SOURCE 


LIBRARY 


EXECUTE 


Sets the loader options necessary for the execution of a PL/I 
program, namely: LOWLOAD and PSETU. 


Loads the object program (A) from the object program file (B*). 


Loads the enclosed object program (B). 


Loads the object program (C) from the object program file (B*). 


Loads the enclosed object program (D). 


Loads the object program (E) from the object program file (B*). 
Searches the user-supplied library (U1) to resolve any 
undefined SYMREFs, then the secondary system standard library 
(*L) and the system standard library (L*). 


Passes control to the object program at the appropriate entry 
point. 
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LOADER CONTROL CARDS 


Loader control cards give information to the General Loader about the 
object programs that are to be executed. These control cards indicate the 
beginning, end, and entry point name for the object programs and define options, 
libraries, and memory allocation methods. In addition, the program can be 
divided into overlay segments by the use of the loader control card $ LINK, A 
more detailed description of these and other loader control cards can be found 
in the General Loader manual and Control Card Reference Manual. 


The loader control cards described in this manual are summarized in Table 
5-1. Following the table, the cards are described in more detail. 


Table 5-1. Loader Control Cards 


End Object deck. 


DKEND 


ENTRY Specify SYMDEF name to which 


Loader passes control. 


EXECUTE Conclude loading and pass 


control to object program, 


sense switches, 
dump option 


FFILE Describe nonstandard file options 


control blocks and options. 


LIBRARY 


file codes of 
user libraries 


Include user libraries 
to resolve SYMREFs, 


LINK Define overlay structure, segment names, 


option 


OBJECT Begin object deck. 


OPTION 


Define Loader options options 


SOURCE Read object program from 


object program file (B*), 


USE 


Define Labeled Common Block name and size 


or SYMREF., 


lRefer to the General Loader manual for a detailed description of the 
parameters, 
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DKEND Co Card 


The $ DKEND control card Indicates the end of the absolute or relocatable 
deck. The PL/I compiler generates this card at the end of the Ob IEEe deck. The 
$¢ DKEND card has the following format: 

1 8 16 61 666 8 


$ DKEND 


time of compilation 


date of compilation 


deck name (n characters, n = 0-4) 
sequence number (8-n characters) 


ENTRY Control Card 


The $ ENTRY control card specifies the name to which the loader passes 
control upon the completion of the loading process. The $ ENTRY control card 
has the following format: 


1 8 6 
$ ENTRY name 
where: name is a SYMDEF corresponding to an external entry point name 


for the program. 


If this card is not included, the loader passes control to either the first 
external entry name that has the OPTIONS (MAIN) attribute in its PROCEDURE 
statement or to the special SYMDEF ..... ., if present. 


EXECUTE Control Card 


The $ EXECUTE control card causes GCOS to activate the loader to load all 
the programs in the activity. The options on the $ EXECUTE control card request 
the setting of sense switches and the form of the dump. The $ EXECUTE card has 
the following format: 


Oe ee A oe AE ns ne ee ee 
$ EXECUTE options 
where: the following options can appear: 
ON1 Set sense switch 1 on. 
ON2 Set sense: switch 2-on. 
ONS Set sense switch 3 on. 
ONG Set sense switch 4& on. 
ON5 Set sense switch 5 on. 
ON6 Set sense switch 6 on. 


DUMP Take full dump if activity terminates abnormally. 
NDUMP Dump only registers if activity terminates abnormally. 
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If no options are requested on the $ EXECUTE control card, all sense switches 
are set off and only the registers are dumped on abnormal termination of an 
activity, 


FFILE Control Card 


The $ FFILE control card describes nonstandard file control blocks and 
nonstandard file options. This control card is described later, in the section 
on "External Files", 


IBRARY Control Card 


The $ LIBRARY control card directs the loader to search the user-supplied 
libraries whose file codes are given as parameters. The libraries are searched 
in the order in which they appear on the card. The format of the $ LIBRARY card 
is as follows: 


1 8 16 
$ LIBRARY f¢,.%4 


where: fc is the 2-character alphanumeric file code of the user library. 


Consider the following card: 
$ LIBRARY Al1,C2 


If this card is included, the loader searches the user library identified by the 
file code Al and then the user library identified by C2 to resolve SYMREFs, 


LINK Control Card 


The $ LINK control card defines the overlay structure, The parameters on 
this card define the name of the segment, and optionally the name of the 
previously defined segment to be overlaid by this segment and the NOPAC option, 
The format of the $ LINK card is as follows: 


1 8 16 


$ LINK seg-name| ,oseg-name| , NOPAC] | 

where: seg-name is the name of the segment composed of the programs 
following the control card up to the next $ LINK or 
$ EXECUTE control card. 


oseg-name is the name of the previously defined segment to be 
overlaid. 


NOPAC indicates that SYMDEFs in the overlaid segment can be 
referenced. 
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The $ LINK control card is described in more detail later in this section 
in connection with the definition of overlay structures. 


OBJECT Control Card 


The $ OBJECT control card indicates the beginning of the absolute or 
relocatable deck. The PL/I compiler generates this card at the beginning of the 
object program produced as a result of the translation of the source program. 
Identification is included on the card in the following format: 


déd 80 


8 16 


EA 


$ OBJECT 


TTL date (see *TITLE description, Section IV) 


deck name (n characters, n = 0-4) 
sequence number (8-n characters) 


For example: 


$ OBJECT F 111574CALC0000 


indicates the following: 


col 60 = P The card was generated by the PL/I 
compiler. 

col 67 - 72 = 111574 TTL date is November 15, 1974. 

col 73 - 76 = CALC The deck name is 'CALC'. 

col 77 - 80 = 0000 The sequence number is 0. 


OPTION Contro rd 


The $ OPTION control card specifies options for the loader. The $ OPTION 
card has the following format: 


1 8 16 
$ OPTION options 


where: option describes the execution of the program and the output of the 
loader. 


The options that can be specified are given in. -Tabie 5-2. 
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Table 5-2. Loader Options 


rr Option 
Name Meaning Default 


A A LE OY DLS I LE DL DNR, OG IIL, es GBA DLO, OTOP ELE LLL Le RIO Oa NEE, 
Generate a memory map. MAP 
Do not generate a memory map. MAP 


Execute even if errors detected. CONGO 


GO Execute only if no errors detected. CONGO 


NOGO Do not execute, CONGO 


ERCNT/n/ | Abort the program if the total ERCNT/150/ 
number of errors exceeds n. 


SYMREF Include the SYMREF symbols used by NOSREF 
each subprogram in the memory map. 


NOSREF Do not include SYMREF symbols in NOSREF 
the memory map. 


PL1 Specify all necessary conditions 
for the execution of PL/I programs 
(LOWLOAD, PSETU). 


NOMSUB Suppress the missing routine message. 


| 


URCE Control] rd 


The $ SOURCE control card is generated by GCOS on the loader control file 
(R*) when a system call card (for example $ PL1) is encountered. The format of 
the $ SOURCE card is as follows: 


i 8 16 
$ SOURCE 


This card indicates that the object program input for the loader is to be found 
on the object program file (B*). 
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USE Control Card 


The $ USE control card specifies a name for the Labeled Common Block or 
SYMREF. A numeric size enclosed in slants’ immediately following the name 
defines the name to be a Labeled Common Block; otherwise, the name is assumed to 
be a SYMREF. The format of the $ USE control card is as follows: 


1 8 16 
$ USE name[/size/],... 


where: name is the name of a Labeled Common Block or SYMREF. 


size is the amount of storage to be set aside for the Labeled 
Common Block, 


The loader enters the name in its symbol table and, if a size is given, sets 
aside the necessary storage. 


Consider the following example: 


$ USE ALPHA/400/,PXY,BETA/200/ 


ALPHA is a Labeled Common Block 400 words long. 
PXY is a SYMREF 
BETA is a Labeled Common Block 200 words long. 


The $ USE control card is necessary for the attachment of INTERACTIVE, INDEXED, 
and REGIONAL files. This usage is described later, in the section describing 
file attachment. 


OVERLAY STRUCTURE 


A program that exceeds main storage capacity can be executed as an overlay 
structure, By the use of $ LINK control cards, a program is divided into a 
series of segments. These segments share storage and, therefore, must be loaded 
during the execution of the program as they are needed, 


The definition of the overlay structure by $ LINK control cards, the tree 
representation for an overlay structure, and the routines used to load overlay 
segments are described in the following paragraphs. 


The $ LINK control cards delimit the segments of the overlay structure. A 
$ LINK control card with a segment name defines as the named segment the 
programs between that card and the next $ LINK or $ EXECUTE card, The segment 
name consists of one to six alphanumeric characters, the first of which must be 
alphabetic. Segment names must be unique with respect to SYMDEFs and other 
segment names. 
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Consider the following fragment of an input deck: 


object program Al 
DK END 
PL1 

source program A2 
LINK BSEG 


Pid 
source program Bl 


$ LINK CSEG 


$ 
$ 
$ 
$ 
$ 
$ 


Two segments are defined in this fragment: ASEG and BSEG. The segment ASEG 
consists of the object program Al and the object program produced as a result of 
the compilation of the source program A2. The segment BSEG consists of the 
object program produced as a result of the compilation of the source program Bl. 


Root Segm 


The main segment of the overlay structure, the root segment, remains in 
main storage through the entire activity. The programs in the input deck 
preceding the first $ LINK control card make up the root segment. The loader 
generates the name '//////' for the root segment. 


The $ LINK control card with two segment names as parameters defines a 
segment overlay. For example: 


$ LINK DSEG,BSEG 
This card indicates that the segment DSEG is defined by the programs following 
and that the segment DSEG overlays the previously defined segment’ BSEG. The 


loader assigns the segment DSEG to the same starting location as the segment 
BSEG. 


Example of an Overlay Setup 


An input deck defining an overlay structure is given here. Following the 
deck setup a diagram of the memory allocation produced by the loader is given. 
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Consider the input deck: 


1 8 16 

$ SNUMB 

$ IDENT 

$ OPTION PLI 

$ PL1 root segment 


source program 
for root segment 
$ LINK ABC 
PL1 
source program 


segment 


$ LINK. DEF 
$ PL1 
source program 


segment 


| 


LINK GH | 
PL 
source program 


AH 


segment 


$ LINK JKL,GHI 
$ PL1 
source program 


segment 


| 


$ LINK MNO,DEF 
$ PL1 
source program 


segment 


LINK PQR, ABC 
PL1 
source program 


LT Hf 


segment 


| 


LINK STU 
PL1 
source program 


AHA 


segment 


| 


$ LINK VWX,STU 
$ PL1 
Source program 


segment 


| 


$ EXECUTE 


ABC 


DEF 


GH | 


JKL 


MNO 


PQR 


STU 


VWX 


This input deck defines a root segment and eight overlay segments, namely: ABC, 
DEF, GHI, JKL, MNO, PQR, STU, and VWX. The segments JKL and GHI 
other, as do segments MNO and DEF, PQR and ABC, 
in this example is made up of a single source program. However, 
can be made up of any number of source and object programs as is illustrated in 


a more general example later in this section. 


and VWX and STU. 


overlay each 
Each segment 
the segments 
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co 


The loader allocates storage based on the $ LINK control. card. The 
allocation of storage can be diagrammed in the following way: 


high address 


LEPL ES 


root segment 


low address 


The solid horizontal lines in this diagram indicate the points at which the 
loader resets its loading origin as a result of encountering a $ 1INK~ control 
card with two segment names. The broken horizontal lines indicate the end of 
the shorter overlay segment. 


Tree Representation 


A tree provides a convenient form of representation for an overlay 
structure. The tree representation for the structure just described is: 


ee 7 
ABC PQR 
letcacdiotadaacte) 
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A tree representation makes explicit the notion of the path. A path is a 
route that can be traced from the root of the tree to one of the tips. The 
paths of the above tree are: 


//////-ABC-DEF-GHI 
//////-ABC-DEF-JKL 
//////-ABC-MNO 
JiLTL IH PQRASTU 
//////-PQR-VWX 


If two segments are connected by a path, these segments are said to be 
common to a path. Notice that the root segment, //////, is common to every path 
of the tree. The segments ABC and JKL are common to a path, namely: the second 
path on the above list of paths. The segments ABC and VWX are, however, not 
common to any path of the tree. 


References Between Segments 


Programs can reference other programs in the same segment or _ programs 
contained in segments on a common path with their containing segment. If there 
is no common path between two segments, the programs of one segment cannot 
reference the programs of the other segment. Programs of segments not ona 
common path share storage and are, therefore, not usually in memory at the same 
time. 


Programs of segments on separate paths can communicate with each other 
through the root segment or through a segment closer to the root segment that is 
common to both paths. For example, the program S of segment STU cannot 
communicate directly with the program V of segment VWX, but both S and V can 
communicate with the program P of segment PQR since there is a path through PQR 
and STU and through PQR and VWX. 


The loader prohibits references between programs belonging to segments on 
separate paths by removing the names defined in overlaid segments from its 
symbol table. References to such names therefore become undefined. 


lt sometimes happens, however, that segments on separate paths co-exist in 
memory. Consider, in the previous example, the segments GHI and MNO. Clearly, 
the loading of MNO does not in any way affect the contents of GHI, if GHI is in 
memory. The NOPAC option of the $ LINK control card allows’ programs in a 
segment to reference programs in an overlaid segment. If the program M of 
segment MNO references the program G of segment GHI, the $ LINK control card 
defining the segment must be: 


$ LINK MNO,DEF, NOPAC 
The NOPAC option directs the loader to omit the step that removes the names 


defined in the overlaid segment DEF from the symbol table. These names are then 
available to the programs of MNO, and the reference from M to G is defined. 
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Loading Segments 


The loader converts each segment into a load module stored on the program 
link file (H*), which is provided by the system (as a temporary file) if it is 
not provided by the user. The loader then loads the root segment into main 
storage and passes control to any entry name within the root segment. The 
user's program is responsible for loading the overlay segments into main storage 
as they are needed. Two programs, PLINK and PLLINK, are provided in the PL/I 
Standard library to accomplish this loading. These two programs differ from 
each other only in the way in which control is returned. 


PLINK loads the segment named as its argument from the program link file 
(H*) and passes control] to the entry name defined by the use of the 
$ ENTRY control card, 


PLLINK loads the segment named as its argument from the program link file 
(H*) and returns control to the statement following the call to 
PLLINK. 


Consider the following portion of an overlay segment: 


i 8 16 


The following two examples illustrate the loading of the segment XSEG, first 
using PLINK and then using PLLINK., 


5°15 DEO4 


EXAMPLE USING PLINK 


The subprogram PLINK is used to load and transfer control to the entry name 
B in the segment XSEG in the following example: 


PROG1: PROCEDURE; 


DECLARE PLINK ENTRY (CHARACTER(6)); 


CALL PLINKC’XSEG *)3 


EXAMPLE USING PLLINK 


The subprogram PLLINK is used to load the segment XSEG in the following 
example. Control is subsequently transferred to the segment XSEG by the call to 
the entry name B. 


PROG2: PROCEDURE; 


DECLARE PLLINK ENTRY(CHARACTER(6) ); 


CALL PLLINK('XSEG '); 


EXAMPLE OF THE USE OF OVERLAYS 


The deck setup for an example using overlays is given here. The tree 
representation defined by the overlay structure and a diagram of the processing 
of this example by the loader are also included. Note, in’ this example, that 
¢ ENTRY cards for the overlay segments are not required since only PLLINK is 
used, 
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SS SSSSaaQg a === ———w 


8 6 
SNUMB 
IDENT 
OPTION PLI1 


PROCEDURE OPTIONS(MAIN) ; 
DECLARE PLLINK ENTRY(CHARACTER(6)); 


CALL PLLINK('SEG1 '); 
CALL X; 


CALL PLEINKESEGH "3s 


LINK SEG1 


PROCEDURE; 
DECLARE PLLINK ENTRY(CHARACTER(6)); 


PLLINK('SEG2 '); 
£3 


B 3 


PLLINK('SEG3 '); 
i 


Wi 
| 
jp 
~~ 
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Deck Setup for Example OVLY (cont) 


1 8 16 


$ LINK SEG2 


PROCEDURE; 


$ LINK SEG4,SEG1 
$ Pid 


$ EXECUT 
$ LIMITS 
§ ENDUJOB 
*** EOF 
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Tree Representation for QOVLY 


The overlay structure defined by the input deck of the previous section can 
be represented by the following tree: 


SEG2 
SEG3 
Z V 
Le eda ensae ee rere 4 
SEG4 
SEG1 
X Y 
bc acter | se hs ita liao it a! 
C 
| 
B 
F445 4 7 | 
root segment 
A 


Loader Processing of OVLY 


The processing done by the loader in connection with OVLY is diagrammed in 
Figure 5-2. As in Figure 5-1, the loader inputs control cards and object 
programs from the loader control file (R*) and object decks, produced as a 
result of translation, from the object program file (B*). The loader searches 
the secondary system standard library file (*L) and the system standard library 
(L*¥). In addition, this example illustrates the construction of load modules on 
the program link file (H*), 
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Loader control file 


(Reh 


$ OPTION PLI 


SOURCE (A: PROCEDURE) 


ENTRY A 


LINK SEG1 


LINK SEG2 


fF fFinAnr Fi Ft RIL Fr Ri re Hi se APA 


(L*) 
system standard 
library file 


(*L) 


secondary system 


ek canal ae 


Main Storage 


Pere es es 


root segment 


Figure 5-2. 


SOURCE (B: PROCEDURE) 


SOURCE (C:PROCEDURE) 


SOURCE (X:PROCEDURE) 


SOURCE (Z:PROCEDURE) 
LINK SEG3,SEG2 
SOURCE (V: PROCEDURE) 


LINK SEG4,SEG1 


SOURCE (Y: PROCEDURE) 


$ EXECUTE 


Object program file 
C*Ba" 3 


OBJECT 
object program A 
DKEND 


OBJECT 
object program B 
DKEND 


if 
tPA 


OBJECT 
object program C 
DKEND 


OBJECT 
object program X 
DKEND 


OBJECT 
object program Z 
DKEND 


A AA 4 


OBJECT 
object program V 
DKEND 


OBJECT 
object program Y 
DKEND 


LOADER | 


Program link file 
Ci He?) 


Loader Processing of Overlays 
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SECTION VI 


EXTERNAL FILES 


This section describes the basic concepts of file processing: organization, 
access, and transmission. The device assignment control cards’ and the 
requirements of the different devices are also included. 


FILE ORGANIZATION 


GCOS PL/! allows the following four types of file organization: 


CONSECUTIVE 
INTERACTIVE 
INDEXED-\ ya 
REGIONAL \ ©” © ~ 


In CONSECUTIVE and INTERACTIVE organization, records are retrieved in the order 
in which they were written; in INDEXED and REGIONAL organization, records are 
retrieved by means of a key. The four types of organization are described in 
detail in the following sections of the manual. For each type of organization, 
the data transmission statements that can be used are given and the method of 
attachment to external files is described. Examples of file creation and access 
are included for each type of organization. 


The organization can be specified at compile time by the ENVIRONMENT 
attribute. If the organization is not given in the program, it can be specified 
at execution time by a parameter on a control. card. In the absence of 
specification, CONSECUTIVE organization is assumed. 


ACCESS MODE 


Two types of access, sequential or direct, are available; however, the 
organization of the file. imposes some constraints on the type of access that can 
be applied to that file. Table 6-1 summarizes the access mode that can be used 
with each type of organization. The activities permitted for the organization 
and access are also given. 
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Table 6-1. Record-Oriented Access Methods 


AE SA SELLE EN ET EE ST SSE RAR SE 


CONSECUTIVE SEQUENTIAL INPUT 
OUT PUT 


UPDATE 


INTERACTIVE SEQUENTIAL INPUT 
OUT PUT 


INDEXED SEQUENTIAL 
DIRECT 
REGIONAL 


As indicated in the table, CONSECUTIVE and INTERACTIVE files cannot be 
accessed directly and an INDEXED file cannot be opened for DIRECT OUTPUT and 
thus cannot be created directly. The motivation for these restrictions is given 
in the detailed description of file organization later in this manual. 


INPUT 
OUT PUT 
UPDATE 


INPUT 
UPDATE 


SEQUENTIAL INPUT 
OUTPUT 


UPDATE 


DIRECT 


INPUT 
OUT PUT 
UPDATE 


TRANSMISSION 


PL/I uses two types of transmission: stream-oriented transmission and 
record-oriented transmission. The PL/I reference manual contains a detailed 
description of these two transmission methods. 


Stream-Oriented Transmission 


In stream-oriented transmission, the file is considered to be a continuous 
stream of characters. However, the conceptual PL/I stream file is attached to 
an external file that consists of a series of records; consequently, the record 
size must be provided for stream files. If the LINESIZE option is given in’ the 
OPEN statement of an output file, the record size is assumed to be the same as 
the line size. Otherwise, the record size can be given at execution time on 
control cards. 
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There are two PL/I statements for stream-oriented transmission, namely: 


GET 
PUT 


Stream-oriented transmission can be used only with CONSECUTIVE and INTERACTIVE 
files. The structure of INDEXED and REGIONAL files is predicated upon the 
relationship between a key and a record, 


Stream-oriented transmission can access either BCD or ASCII files. Unless 
otherwise specified, the file is assumed to be BCD and is converted during 
transmission to ASCII. Punch stream files are exceptions to this, however (see 
"Device Requirements" in this section and "Descriptor Files" in the section on 
"Consecutive and Interactive Organization"), 


Record-Oriented Transmission 


In record-oriented transmission, the minimum unit to be processed is a 
logical record. No data conversion takes place during transmission, 


A file is considered to be a set of logical records. On OUTPUT, a WRITE, 
REWRITE, or LOCATE statement causes the record to be transmitted to the external 
file exactly as it is recorded internally. A READ statement causes the record 
of the external file to be transmitted to memory. The logical records are 
written on the external file after being blocked by the operating system. Since 
the records are blocked. the execution of a data transmission statement does not 
necessarily cause the record to be actually transmitted between memory and a 
peripheral device. The execution of a CLOSE statement causes any’ records 
retained in the blocking buffers to be transmitted to the device, 


There are five PL/I statements for record-oriented transmission, as 
follows: 


READ 
WRITE 
REWRITE 
LOCATE 
DELETE 


The options that can be used in these statements depend upon the type of 


Organization and the method of access. The permissible data transmission 
statements for each type of organization are given in the sections following. 


RECORD STRUCTURE 


PL/I handles the following record types: 


FIXED 
VARIABLE 


FIXED records can be used with all types of file organization. VARIABLE record 
types can be used only with CONSECUTIVE files. 


b= 3 DEO4 


FIXED Records 


FIXED records are all of the same defined length. The size of the buffer 


determines the number of records to be blocked. No record control word appears 


in fixed length records. 


VARIABLE Records 


For VARIABLE records, a record control word appears at the beginning of 
each logical record. VARIABLE records can be used only with files generated in 
the binary mode. VARIABLE records can contain a record larger than the buffer 
size. Such a record is called a partitioned record. When files with 
partitioned records are handled, the PRTREC option must be requested on the 
¢ FFILE control card. 


ATTACHMENT OF PL/I FILES TO RNAL FILES 


The PL/I file is a conceptual unit. When the OPEN statement for the file 
is executed, the file is attached to an external file by the file code. The 
file code is determined from the first two characters of the TITLE option. If 
the TITLE option is not given, the first two characters of the file name are 
used as the file code. Control cards with the identifying file code are used at 
execution time to specify a device and to provide additional information about 
the file. 


A CONSECUTIVE file can be attached directly to a peripheral device, if all 
the default assumptions apply to the file. To change default assumptions, a 
¢ FFILE control card or a descriptor file can be included. INDEXED and REGIONAL 
files require a descriptor file and a $ USE control card for attachment. Figure 
6-1 illustrates the attachment of files with different types of organization. A 
description of the peripheral device assignment cards is given later in this 
section. The descriptor file cards depend upon the organization of the file and 
are, therefore, described separately under each organization type. Similarly, 
the $ USE is described for INDEXED and REGIONAL files. 


In Figure 6-1, the first file Fl is a CONSECUTIVE file with record-oriented 
transmission. The file Fl is opened with a TITLE option Wl. The file code is 
taken from the first two characters of the TITLE option, so the file code for Fl 
in this example is W1l. All the default assumptions apply to this. file; 
therefore, it can be attached directly by the device assignment card $ TAPE Wl. 
The second file, F2, is a CONSECUTIVE file with stream-oriented transmission. A 
descriptor file is provided for this file to alter the default assumption about 
record size. The third file, F3, is a REGIONAL file; therefore, the necessary 
descriptor file and $ USE control card are provided in addition to the device 
assignment card for a direct access device. The fourth file, F4, is an INDEXED 
file; the necessary descriptor file, $ USE control card, and device assignment 
cards for index and data file are _ provided. The fifth fite, SYSEN,. ts 4 
standard file and needs no control cards. 
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SNUMB 


$ 

$ IDENT 
™» 3 OPTION 

$ PL1 


EX1: PROC; 


Pit 


DCL Fl RECORD FILE ENVIRONMENTC(CONSECUTIVE); 
DCL F2 STREAM FILE; 
DCL F3 RECORD FILE ENVIRONMENTCREGIONAL) ; 
DCL F4& RECORD FILE; 
DCL SYSIN FILE; 


OPEN FILE(F1) 
OPEN FLLECF2) 
OPEN FILE(F3) 
OPEN FILECES). 


OPEN FILE(SYSIN) 


END; 
$ USE 
$ USE 
$ EXECUTE 
$ TAPE 
§ TAPE 
F Zee PRMFL 
$ FILE 
$ ErLe 
$ DATA 
CSP —s—dDATA 


CSP RECORD 


$ DATA 
RSP —sdDATA 
RSP —s- RECORD 


§ DATA 
ISP INDEX 
ISP ——dDATA 


ISP RECORD 


$ ENDJOB 


TITLEC WL”) 
TITLEC'X2* 2) OUTPUT 3 

TETLEC TY1*) DIRECT UPDATE: 
TITLEC’Z1°) KEYED SEQUENTIAL 


INPUT; 


INPUT; 


»RBUF1/2000/, .RBUF2/2/ 
.XBUF1/3000/, .XBUF2/2/ 


Wijews 


Al,..» 
2 ee 
Cd pass 
C2) 4 «% 


X1 
FC=Al 


CHARSZ=100 


v2 
FC=B1 
RECSZ=40 


Z1 


FC=C1,PAGESZ=320 
FC=C2, PAGESZ=320 
RECSZ=20.KEYOFF=0, KEYSZ=12 


Figure 6-1. 


Ww 


File Attachment 


INPUT; 
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Devi Assignment Control Cards 


Device assignment control cards specify the actual device to be used for 
each file and define additional file information. This section. briefly 
describes seven of these device assignment cards. A more detailed description 
of these and information about other file control cards is given in the Control 
Cards Reference Manual. 


Device assignment cards must (1) follow the control card that defines’ the 
activity, and (2) precede any data cards associated with the activity. 


FILE CONTROL CARD 


The $¢ FILE control card allocates a file to a mass storage device. If the 
device type is not given, the file is allocated to the fastest device type 
available. The $ FILE control card has the following format: 


1 8 16 
$ FILE fc,lud,access,device-list 
where: fc is the 2-character alphanumeric file code identifying 


the external file. 


lud is the logical unit designator, a 2- or 3-character 
symbol (followed by a disposition code) identifying 
the file. The first character of the identifier is 
alphanumeric and the remaining characters numeric. 
The following disposition codes can be given: 


R - Release 
S - Save for subsequent activity 
P - Purge 


access indicates the number of links and the file type: 
sequential (L) or random (R). 


device-list specifies a device type preference list for the 
allocation of mass storage. The device types that can 
be given are: 


DSS167 

DSS170 

DSS180 

DSS181 (DSPK) 
DSS190 

DSS191 

DSS270 

nsuosi0 | (MASS ) 
MSU0400 
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Consider, for example, the following $ FILE control card: 

1 8 16 

$ FILE AA,X1S,2L,DSS167,DSS180 
This card requests that the external file with file code AA be assigned to 
DSS167 and, if that device is not available, to DSS180. The file is accessed 


sequentially and occupies two links (2L). The file is to be saved (S) for a 
subsequent activity. 


PRMFL CONTROL CARD 


The $ PRMFL control card is used to access an existing permanent file. The 
$ PRMFL card has the following format: 


1 8 16 
$ PRMFL fc,permit,type,file-string 
where: fc is the 2-character file code identifying the file. 
permit is the allowable access, as follows: 
R - Read 
W - Write 
A - Append 
E or X = Execute 
REC - Recovery 
type indicates sequential (L) or random (R). 
file-string is the file descriptor. lt contains the catalog name, 


password (if needed), and file name. 


Consider, for example, the following $ PRMFL control card: 
1 8 16 
$ PRMFL H*,W,R,ALPHA/ CW 


This card requests the permanent file created by FILSYS on H*. The requested 
access is append (A). The file is random (R), and the file string is ALPHA/CW. 


TAPE CONTROL CARDS 


These cards assign tape units. Three tape control cards are available: 


$ TAPE7 assigns a seven-track tape unit. 

$ TAPE9 assigns a nine-track tape unit. 

$ TAPE meaning may be installation dependent. See the Control Cards 
Reference Manual. 
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The format of the tape control cards is as follows: 


] 8 16 ee ee 


$ TAPE fc,lud,mri,serial,seq,file-name 
TAPE7 
TAPES 
where: fc is the 2-character alphanumeric file code identifying 
the file. 
lud is the logical unit designator, a 2- or 3-character 


symbol identifying the file and a disposition code, The 
following disposition codes can be given: 


S - Save 
C - Continue 
D - Dismount 
R - Release 
r= PURZe 
mri is the multireel indicator. Any nonblank character’ in 
this field indicates a second tape is assigned to the 
file. 
serial is the tape serial number of the first reel of the file. 
seq is the sequence number of the reel at which’ processing 
begins. 
file-name is a 1- to 12-character name given for external 


identification of the file; this name is used to issue 
mounting instructions to the operator. 


SYSOUT CONTROL CARD 


The $ SYSOUT control card assigns the file identified by the file code to 
SYSOUT for online conversion. The $¢ SYSOUT control card has the following 
format: 


doe ee ee eee 


$ SYSQUT: Te 


READ CONTROL CARD 


The $ READ control card allocates the file identified by the file code to 
the card reader. The $ READ control card has the following format: 
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PRINT CONTROL CARD 


The $ PRINT control card allocates the file identified by the file code to 
the line printer. The $ PRINT control card has the following format: 


1 8 16 
$ PRINT Fc 


PUNCH CONTROL CARD 


The $ PUNCH control card allocates the file identified by the file code to 
the card punch. The $ PUNCH control card has the following format: 


: 8 16 
$ PUNCH rc 


Table 6-2 summarizes the device requirements of different devices and 
indicates the type of organization that can be applied to that device. In 
addition, the transmission method and mode for the device are given. 


Table 6-2. Device Requirements 


Allowable Transmission 
Organization Method 


card CONSECUTIVE stream-oriented or BCD (stream) 
reader record-oriented with binary (record) 
fixed length records 


card CONSECUTIVE stream-oriented or BCD or IBMEL 
punch record-oriented with (stream) 
fixed length records binary (record) 


line CONSECUTIVE stream-oriented or BCD 
printer record-oriented with 
fixed length records 


magnetic CONSECUTIVE record-oriented ASCII 
tape stream-oriented Rect) Or -BGe 


mass CONSECUTIVE record-oriented ASCII 
storage stream-oriented RSCi! or-Bco 


INDEXED record-oriented binary 


REGIONAL record-oriented binary 
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SECTION VII 


CONSECUTIVE AND INTERACTIVE ORGANIZATION 


This section describes the attachment of files with CONSECUTIVE and 
INTERACTIVE organization. The general requirements for the attachment of a file 
with CONSECUTIVE organization are followed by examples of the creation and 
access of CONSECUTIVE stream files and record files. The special requirements 
of INTERACTIVE files and an example of the creation and access of an INTERACTIVE 
file concludes the section. 


CONSECUTIVE ORGANIZATION 


A GONSECUTIVE. file can be accessed. only ta-the order th whick it was 
written. For devices like the card reader, punch, and line printer, this is the 
only acceptable form of organization. 


A CONSECUTIVE file can be attached to an external file directly if all the 
default assumptions apply. If a CONSECUTIVE file is attached to a direct access 
device, the SEQUENTIAL file option must be specified. To alter the default 
assumptions for a CONSECUTIVE file, the $ FFILE control card and/or a descriptor 
file can be specified. 


hment_of CONSECUTIVE Fi] 


To specify and attach a CONSECUTIVE file, the following requirements must 
be met: 


% The file must be designated as CONSECUTIVE. The CONSECUTIVE keyword 
can be specified in the ENVIRONMENT attribute at compile time or a 
descriptor file containing CSP cards can be supplied at execution 
time, In the absence of the ENVIRONMENT attribute and a descriptor 
file, CONSECUTIVE organization is assumed. 


8 The file must be assigned to a peripheral device by a $ TAPE, $ FILE, 
$ PRMFL, $ SYSOUT, $ READ, $ PUNCH or $ PRINT control card. 


a To override the default assumptions about buffer size, number. of 
buffers, mode, or record type, the $ FFILE control card can be used. 
The default assumptions are: 


buffer size 320 words 
number of buffers i 
record length variable 
mode binary 
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& To override the default assumptions about record size, tabs, mode, and 
rewinding, a descriptor file of CSP cards can be. provided. The 
default assumptions are given with the explanation of the descriptor 
file, later in this section. 


$ FFILE CONTROL CARD 


For files with CONSECUTIVE organization, the file control block can be 
created using the $ FFILE control card. The format of the $ FFILE control card 
is as follows: 


1 8 16 
$ FFILE TC, OD ClONs« << 
where: fc is the 2-character alphanumeric code identifying the file. 


options describe the nonstandard properties of the file. 


The options of interest to the PL/I programmer are given in the _ following 
list: 


Option Meaning 

STDLBL A standard label is generated and checked. 

NSTDLB No label is generated. 

NBUFFS/n The number of buffers to be used is n, (n = 1 0r 2). 

BUFSIZ/n The size of the buffer is n, where n is a decimal number 
& 4095. 

MODBCD or The recording mode is BCD. 

MBCD 

MODMI X The recording mode is mixed (BCD and binary). 

FIXLNG/n The file contains fixed length records of length n, where n 
< 4095. 

PRTREC The file contains partitioned records. 
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DESCRIPTOR FILE. FOR A CONSECUTIVE FILE 


CONSECUTIVE files can be more fully specified by the use of a descriptor 
file. The descriptor file contains information about the rewinding of the file, 
the character set, format, and record size. 


Two types of control cards are used to provide information about files with 
CONSECUTIVE organization: the CSP DATA card and the CSP RECORD card. Columns 
1- 3 of these cards contain the code CSP to indicate that the cards apply to a 
CONSECUTIVE file. The format of the CSP DATA card ts as follows: 

1 8 16 

CSP DATA FE=fC, Option; ««+ 

where: fc is the 2-character alphanumeric code identifying the file. 


option provides additional information. 


The options that can be used on a CSP DATA card are given in the following list: 


Option Meanin Default 
OLEAVE Open file without rewinding. Rewind on opening. 
LEAVE Close file without rewinding. Rewind on closing. 
LOCK Lock file. Do not lock file. 
ASCH File consists of ASCII Stream file is BCD. 
characters. 
BCD Punch stream file consists Punch stream file as 
oF BCD. IBMEL (see appendix on 
"Character Conversion 
Tables’). 
TAB Set tabs at specified TARCL VIE 2 ho wee 
conlmns,. tes, TABCL,25;19) 
NTAB Print data continuously TABC Lor isae woke 
INTERACTIVE File is INTERACTIVE. File is CONSECUTIVE. 


The CSP ETC control card can be used to continue the CSP DATA card. 


The CSP RECORD control card has the following format: 
1 8 16 
CSP RECORD option 
where: option indicates the size of the record, as follows: 
RECSZ=n The logical record contains a maximum of n- words. 


CHARSZ=n The logical record contains a maximum of n 
characters. 
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EXAMPLE OF CONSECUTIVE FILE ATTACHMENT 


The following fragment illustrates the attachment of a file with 
CONSECUTIVE organization. 


1 8 16 
$ SNUMB 

$ IDENT 

$ OP Trion: Pig 
$ PL1 

EX1: PROC; 


OPEN FILE(F1) OUTPUT TITLE('X1') STREAM; 


PrPibE Al, BUFSIZ/400, NBUFFS/2 
TAPE Al, A1D 

DATA Xl 

CSP DATA FC=Al 

CSP RECORD CHARSZ=100 


AA H 


$ ENDJOB 


The TITLE option in the OPEN statement specifies the file code Xl. A descriptor 
file is included following the $ DATA control card with the file code Xl. The 
descriptor file specifies that the file code is Al and that the size of the 
records of the file is 100 characters. A $ FFILE control card is included to 
alter the default assumptions about the number of buffers and the buffer size. 


Stream-Oriented Transmission 


Stream-oriented transmission can be applied to files with CONSECUTIVE 
organization. Although a stream file is a continuous sequence of characters, it 
is attached to an external file that consists of a series of records. The 
record size of the external file is specified either by the LINESIZE option in 
the OPEN statement (for an output file) or directly on a CSP card. 


EXAMPLES OF STREAM FILE ACCESS 


Figure 7-1 illustrates the creation of a stream file. Data is taken from 
the system input file and placed in the stream file MASTER. The file MASTER is 
attached to an external tape file with records 80 characters long. 


Figure 7-2 illustrates stream file access. The file MASTER created in the 
previous figure is opened, and those entries belonging to the engineering 
department are printed on the system output file. 
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ps 8 16 


$ SNUMB 

$ IDENT 

$ OPTION PLI 

$ FLL 

SFC? PROC OPTIONS(MAIN); 


DCL MASTER STREAM FILE ENVIRONMENTC(CONSECUTIVE); 


UC. SISTN FLLEs 
DCL O01. DIRECTORY, 


02 PLANT CHAR( 16), 
02 DEPARTMENT CHAR(16), 
02 SECTION CHAR( 16), 
02 NAME, 
03 LAST CHAR(16), 
Os FIRST CHAR( 16); 


ON ENDFILECSYSIN) EOFS Ext 1 2 


OPEN FILLECMASTER) OUTPUT LINESIZECS0) .TETLEC™MF")3 
[INSF: GET LISTC PLANT, DEPARTMENT, SECTION,LAST, FIRST); 


PUT FILE(MASTER) LIST(DIRECTORY); 
GOTO INSF; 

EXIT: CLOSE FILE(MASTER):; 
END; 


EAEGUTE 

LIMITS -TO0,40K;=2K 

TAPE Sig Wa 

DATA | x 

CLEVELAND ENGINEERING 33B JONES WALTER 
CLEVELAND PURCHASING 24C SMITH HENRY 
CLEVELAND PURCHASING 24D MARTIN JOSEPH 
PHILADELPHIA PLANNING 224 FRANKLIN ROBERT 
PHILADELPHIA ENGINEERING 335 GEORGE WALTER 
WASHINGTON MARKETING AA45 JENSON THOMAS 
PHILADELPHIA ENGINEERING 336 SMITH CLYDE 
ALBANY PURCHASING XX22156 BURR ARTHUR 
ALBANY ENGINEERING XX223457 HAMILTON NATHAN 
$ DATA MF 

CSP DATA FC=SC 

CSP RECORD CHARSZ=80 

$ ENDJOB 

**x*kEOF 


AHHH 


Figure 7-1. CONSECUTIVE Stream File Creation 
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$ SNUMB 

$ IDENT 

$ OPTION. -PLI 

$ PL1 

SFA: PROC OPTIONS(MAIN) ; 


DCL MASTER STREAM FILE ENVIRONMENTC(CONSECUTIVE) ; 
DCL. SYSPRINI FILE? 
DEL BL DIRECTORY , 


02 PLANT CHAR(16), 
02 DEPARTMENT CHAR( 16), 
02 SECTION CHAR( 16), 
02 NAME, 
03 LAST CHAR( 16), 
O05 FIRST CHAR( 16), 


ON ENDFILE(MASTER) GOTO EXIT; 
OPEN FILE(MASTER) INPUT; 
LOOP: GET FILE(MASTER) LIST(DIRECTORY) ; 
IF DEPARTMENT = "ENGINEERING" 
THEN PUT SKIP LIST(DIRECTORY); 


GOTO LOOP; 
EXIT: CLOSE FILECMASTER); 
END; 
$ EXECUTE 
$ LIMITS 10,40K,-2K, 20000 
$ TAPE SA,X1D 
$ DATA MA 


CSP DATA FC=SA 
CSP RECORD CHARSZ=80 
$ ENDJOB 


Figure 7-2. CONSECUTIVE Stream File Access 


DEO4 


Record-Oriented Transmission 


Records of a CONSECUTIVE file have no key and are retrieved in the order in 
which they are written. A CONSECUTIVE file is created by the execution of a 
sequence of WRITE statements with the SEQUENTIAL OUTPUT attribute. Once the 
file is created, it can be accessed by READ statements with the SEQUENTIAL INPUT 
or SEQUENTIAL UPDATE attributes. The REWRITE statement cannot be used for a 
file with CONSECUTIVE organization. 


DATA TRANSMISSION STATEMENTS 


The data transmission statements that can be used to create and access a 
CONSECUTIVE RECORD file are given in Table 7-1. Braces are used to group 
alternative forms, each written on a separate line. Brackets are used to 
indicate a construct that is optional. 


Table 7-1. Data Transmission Statements for CONSECUTIVE RECORD Files 


SEQUENTIAL OUTPUT 


WRITE FILE(file-name) FROM(variable-name) ; 


LOCATE based-var FILE(file-name SET( pointer-var) 


e 
r 


SEQUENTIAL INPUT or SEQUENTIAL UPDATE 


INTO(variable-name) 
READ FILE(file-name) SET( pointer-var) } . 
IGNORE(Cexpression) 


EXAMPLES OF RECORD FILE ACCESS 


Figure 7-3 illustrates the creation of a CONSECUTIVE RECORD file and Figure 
7-4 illustrates the access of the file just created. 
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$ SNUMB 

$ IDENT 

$ USERID SMCNAME$ PASSWORD 
$ UPTTON PLL 

$ PL1 LIST 


CEC: PROC OPTIONS(MAIN); 
DCL DISC RECORD SEQUENTIAL FILE ENVIRONMENT( CONSECUTIVE); 
DCL SYSIN FILE; 
DCL 01 IMAGE, 


02 NAME, 
03 LAST CHAR( 30), 
03 FIRST CHAR( 30), 
02  Oriy CHAR( 30), 
02 STATE CHAR( 26), 
02 CODE CHAR( 4); 


ON ENDFILEC(SYSIN) GOTO EXIT; 
OPEN FILEC DISC) OUTPUT; 

LOOP: GeT EUSTUCLCAST, PIRS), CV LY: S1ATE, CODE): 
WRITE FILECDISC) FROM(C IMAGE); 


GOTO LOOP; 
GATTS “CEOSE- FILECD TSC s+ 
END; 
$ EXECUTE 
$ LIMITS 10,20K,-2K 
$ PRMFL DF,W,S,DATA/BANK 
$ DATA DI 


CSP DATA FC=DF 

CSP RECORD RECSZ=30 

$ DATA | 

JONES ROBERT PHILADELPHIA PENNSYLVANIA AA 
SMITH HENRY WAKEFIELD OHIO AB 

SMITH ROBERT STONEHAM CALIFORNIA AA 
SMITH MARY STONEHAM CALIFORNIA BA 
SMITH CHARLES RANDOLPH MARYLAND AA 
SMITH MARTIN SHARON WASHINGTON BA 
SMITH CHARLES NORWOOD FLORIDA BA 

$ ENDJOB 


Figure 7-3. CONSECUTIVE RECORD File Creation 
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1 8 16 


$ SNUMB 

$ IDENT 

$ USERID SMCNAME$ PASSWORD 
$ OPTION PLI1 

$ PL Last 


CFA: PROC OPTIONS(MAIN) ; 
DCL (DISC,ATAPE) RECORD SEQUENTIAL FILE ENVIRONMENT(CONSECUTIVE); 
DCL 01 IMAGE, 
02 NAME, 
03 LAST CHAR( 30), 
O35 FIRST CHAR( 30), 


02 CL TY CHAR( 30), 
02 STATE CHAR( 26), 
02 CODE CHAR( 4); 


ON ENDFILECDISC) GOTO EXIT; 
OPEN FILECDISC) INPUT: 
OPEN FILECATAPE) OUTPUT; 
LOOP: READ FILEC(DISC) INTOCIMAGE); 
IF CODE = "AA" THEN WRITE FILECATAPE) FROM( IMAGE); 
GOTO LOOP; 
Exede CLOSE FILEethisc): 
CLOSE FILECATAPE): 
END; 


EXECUTE 

LIMITS 10,20K,=-2K 

TAPE TPaALS 

FePLE TF,NBUFFS/2, BUFSIZ/640 
PRMFL DF,R,S,DATA/BANK 
DATA DI 

CSP DATA FC=DF 

CSP RECORD RECSZ=30 

$ DATA AT 

CSP DATA FC=TF 

CoP RECORD RECSZ=30 

$ ENDJOB 

** * EOF 


PAPHHAA HH 


Figure 7-4, CONSECUTIVE RECORD File Access 


INTERACTIVE ORGANIZATION 


TO communicate with a remote terminal in the DIRECT PROGRAM ACCESS mode, a 
stream file with INTERACTIVE organization is used. 


hment of an INTERACTIVE Fil 


To specify and attach a file with INTERACTIVE organization, the following 
requirements must be met: 


@ The file must be designated as INTERACTIVE. The INTERACTIVE keyword 
can be specified in the ENVIRONMENT attribute at compile time or the 
INTERACTIVE attribute can be specified on the CSP DATA card at 
execution time. 


F) A $ USE .RTYP control card must be included before the $ EXECUTE 
control card to cause the loading of the proper File and Record 
Control routine for accessing the terminal. 


7-9 DEO4 


e A $ DAC control card must be included to provide direct access 
capability between a remote terminal and a program in execution, 


The $ DAC control card contains the file code and a single character that 
is to be appended to SNUMB identifier to provide an inquiry name. 


Example of INTERACTIVE Files 


Figure 7-5 gives a program fragment illustrating the attachment of two 
INTERACTIVE files. The inquiry name for this example is '123451I'. 


1 8 ND ee 
$ SNUMB 12345 

$ [DENT 

$ OPTION PLI1 

$ PLa 

IFAC: PROC; 


DCL Dl STREAM FILE ENVIRONMENTCINTERACTIVE) ; 
DCL D2 STREAM FILE ENVIRONMENTCINTERACTIVE) ; 


OPEN FILE(D1) INPUT TITLE("AB"); 
OPEN FILE(D2) OUTPUT LINESIZE(120); 


GET PILECDL) LESTtx); 


PUT FILE(D2) LIST(Y); 


END; 
$ USE SRITP 
$ EXECUTE 
$ DAC oe 
$ DAC X24 
$ DATA AB 


CSP DATA FC=X1, INTERACTIVE 
CSP RECORD RECSZ=10 

$ DATA D2 

CSP DATA FC=X2, INTERACTIVE 
CSP RECORD CHARSZ=120 

$ ENDJOB 

*** EOF 


Figure 7-5. Attachment of INTERACTIVE Files 


7720 DEO4 


SECTION VIII 


INDEXED ORGANIZATION 


This section describes the access and structure of files with INDEXED 
organization. The method of attachment for an INDEXED file and the utilization 
report produced as a result of using an INDEXED file are given. Examples of the 
creation and access of an INDEXED file are included. 


INDEXED files are processed by the Index Sequential Processor (ISP) in 
Gcos. For additional information on INDEXED files, refer to the Indexed 
Sequential Processor manual. 


INDEXED FILE ACCESS 


A file with INDEXED organization consists of a series of records, each 
containing an imbedded key. The imbedded key is a character string within the 
record. The length of the imbedded key and the position of the key within the 
record are specified on a control card at execution time. The maximum length 
for a key is 32 characters. 


File Creation 


Records in an INDEXED file are arranged in the order defined by the 
imbedded keys. To create an INDEXED file, the file is opened for SEQUENTIAL 
OUTPUT and records are written so that the imbedded keys are in order with 
respect to the ASCII collation sequence. The execution of a WRITE statement 
during file creation for a record whose imbedded key is lower in the ASCII 
collation sequence than the key of a previously written record causes the KEY 
condition to be raised. 


Once a file is created, additional records can be inserted. The file is 
opened for UPDATE and records are logically inserted in the file according to 
the position of its imbedded key in the ASCII collation sequence with respect to 
the keys of the other records of the file. The structure of the file is 
described later in this section. 


File Access 


An INDEXED file can be accessed either sequentially or directly. 
Sequential processing accesses records in the order defined by the imbedded 
keys. Direct processing accesses a record by matching the source key from the 
data transmission statement to an imbedded key within the file. 
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SEQUENTIAL ACCESS OF AN INDEXED FILE 


When an INDEXED file is accessed sequentially, the source key is. not 
required. Records are accessed in the order of the imbedded keys. If no 
records have been added to the file since its creation, the order of the 
imbedded keys is the same as the order in which the records were written. 
However, if a record has been added with an imbedded key lower in the ASCII 
collation sequence than the key of the last record of the file, the order of the 
imbedded keys is different from the order in which the records were written. 


For example, if a file is created with records having keys: 
A, By D, ae l, oo Ae X 


and then an additional record is added with the key G, the order of the imbedded 
keys is: 


ge B05 Fe in Eig Po Te -o 


Sequential processing of the file retrieves the records in the above order. 


In SEQUENTIAL UPDATE, the execution of a DELETE statement without the KEY 
option causes the most recently retrieved record to be eliminated. If the FROM 
option does not appear in a REWRITE statement, the execution of that statement 
causes the record just retrieved to be replaced. 


DIRECT ACCESS OF AN INDEXED FILE 


All direct access data transmission statements must include either the KEY 
or the KEYFROM option. Files can be opened either for INPUT or UPDATE. 


In direct mode, records can be read, replaced, eliminated, or added. The 
source key must be specified on the data transmission statement. The source key 
is compared against the imbedded keys of the file, using the rules that govern 
character string comparison. If no match is found for the source key specified 
with a READ, REWRITE or DELETE statement, the KEY condition is”7 raised. be ne 
match is found for the source key specified with a WRITE statement, the KEY 
condition is also raised, indicating that the key of the record to be added is 
already contained in the file. 


Data Transmission Statements for INDEXED Files 


Table 8-1 lists the data transmission statements that can be used with 
INDEXED files. 


Braces are used to group alternative forms, each written on a= separate 
line. Brackets are used to indicate a construct that is optional. 
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Table 8-1. Data Transmission Statements for INDEXED Files 


rm™ SEQUENTIAL OUTPUT 


WRITE FILECfile-name) FROM( variable-name) [ KEYFROM( expression) | ; 


LOCATE based-var FILE( file-name)[ KEYFROM( expression) | [ SETCpointer-var)]; 


SEQUENTIAL INPUT 


INTO(variable-name) KEY ( expression) 
READ FILE(file-name) v 
SET( pointer-var) KEYTO( char-strng-var) 
READ FILEC(file-name) IGNORE( expression); 
SEQUENTIAL UPDATE 
INTO( variable-name) KEY( expression) 
READ FILECfile-name) ; 
SET( pointer-var) KEYTO( char-strng-var) 
READ FILECfile-name) IGNORE(expression) ; 
” 
REWRITE FILE(file-name)[ FROM(variable-name) | ; 
DELETE FILE(file-name) ; 
DIRECT INPUT 
READ FILE(file-name) INTO(Cvariable-name) KEY(expression) ; 
DIRECT UPDATE 
READ FILE(file-name) INTO(variable-name) KEY(expression) ; 
REWRITE FILE(file-name) FROM(variable-name) KEY(expression) ; 
WRITE FILECfile-name) FROM(variable-name) KEYFROM(expression) ; 
DELETE FILE(file-name) KEY(expression) ; 
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STRUCTURE OF AN INDEXED FILE 


An INDEXED file consists of two separate files, namely: a data file, 
containing the written records of the INDEXED file, and an index file, 
containing information about the position of the keys within the data file, for 


efficient access. These two files are separate and can be stored on separate 
direct access devices. 


Pages 


The data file and the index file, like all direct access files, are divided 
into pages. A page is the unit of information passed between random access 
storage and main memory during processing. The page size and the percentage of 
the page to be filled can be specified on control cards at execution time. 


Relationship Between the Data File and the Index File 


For every page in the data file, an entry exists in the index file, called 
a fine index. When the fine index exceeds one page, a coarse index is built. 
The coarse index portion of the index file contains an entry for every page _ in 
the fine index portion. 


When an INDEXED file is accessed directly, the index file is used to 
efficiently locate the desired record in the data file, as follows: 


oF The source key from the data transmission statement is compared to the 
entries in the coarse index to obtain the page number in the fine 
index. 

2 The source key is compared to the entries on the designated fine index 


page to obtain the page number in the data file. 


a The source key is compared to the keys on the designated data file 
page to obtain the desired record. 


Structure of the Data File 


The data file begins with a record containing 62 words’ of control 
information and concludes with an end-of-file. The data file contains’ the 
records written; each record contains, in addition to the key and data, a record 
control word and ae pointer. The record control word specifies the record 
length, record type, and deletion’ status. The pointer specifies the next 
logical record according to the order of the imbedded keys. 


Records can be variable in length; but the key must be located at the same 
position in every record. The pages of the data file are filled with records. 
If there is not sufficient space on a page to accommodate an entire record, the 
space is left unused and a new page is started. 


The pages of the data file that are not filled with records during file 
creation are called overflow pages. These overflow pages can be used for 
records added after file creation. 
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Space for the addition of records can be reserved uniformly throughout the 
file by specifying a percentage fill figure at execution time. The percentage 
fill parameter jis described later in this section in connection with the 
descriptor file. The uniform distribution of space throughout the file is 
useful if records with keys distributed throughout the file are to be added 
after file creation. 


Figure 8-1 illustrates the structure of the data file. Record #3 was added 
to the file after file creation and is, therefore, stored physically on an 
overflow page and linked into its logical position within the file. If space 
had been reserved uniformly throughout the file, this record could possibly have 
been located physically on the page to which it logically belongs. 
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OVERFLOW AREA 
page 1 page n 


A 


() 


a page control word a page control word 
Data utilization record record control word 
ontrol]l word 


utilization 


record (62 words) record #3 


Link to #4 
record control word 


record #1 
Link to #2 
record control word 
record #2 
k to # 
record control word 


record #4 


Link to # 


unused space 


page 2 


Data page control word 
record control word 


record #5 


Figure 8-1. Structure of the Data File 
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Structure of the Index File 


The index file begins with a record containing 64 words of control 
information and concludes with an end-of-file. The fine index is created in 
ascending order from the beginning of the file. When the fine index portion 
exceeds one page, the coarse index is created in descending order from the end 
of the file. If the fine index and the coarse index overlap, an error message 
is produced and the program is aborted. Guidelines for determining the size _ of 
the index file are given later in this section. The size of the index file is 
related to the page size of the data file; the larger the page size in the data 
file, the fewer fine index entries in the index file. 


Figure 8-2 illustrates the structure of the index file. 
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index utilization record page 1 


Fine index (page 1) 


fine index (page 2) page 2 


Fine index (page 3) page 3 


coarse index (page 2) page n-l 


coarse index (page 1) page n 


coarse index (page 3) | page n-2 


n = number of pages allocated to the index file. 


Figure 8-2. Structure of the Index File 
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ATTACHMENT OF AN INDEXED FILE 


To specify and attach an INDEXED file the following requirements must be 
met: 


# The file must be designated as an INDEXED file. The INDEXED keyword 
can be specified in the ENVIRONMENT attribute at compile time or, if 
no ENVIRONMENT attribute is given, a descriptor file containing ISP 
cards can be supplied at execution time. 


é A descriptor file must be provided to specify the file codes of the 
data file and index file and the record and key sizes. 


€ A device assignment control card for a direct access device must _ be 
provided for both the data and the index files. 


é The size of the work region to be reserved for INDEXED files must be 
specified on an appropriate $ USE control card. 


Descriptor File for an INDEXED File 


Each INDEXED file must have an associated descriptor file that specifies 
the fite code of the data file and the file code of -the tndex fie, In 
addition, the maximum record size and key size must be given. 


Optionally, the page size and percentage fill for both the data file and 
the index file can be specified. In the absence of specification, the page size 
is assumed to be 320 words with 100% fill. 


If the key is not located at the beginning of the record, the key offset 
must be specified. Records can be variable in length, but the offset of the key 
within the record must be fixed. 


The format of the cards in the descriptor file is now given. A discussion 
of the parameters and some guidelines for their selection follow the card format 
description. 


CONTROL CARDS FOR INDEXED FILES 


Three types of control cards are used to provide additional information for 
files with INDEXED organization: the ISP INDEX card, the ISP DATA card, and_ the 
ISP RECORD card. 

The ISP INDEX card has the following format: 

1 8 16 

ISP INDEX FC=fc[,PAGESZ=1PS| 


where: fc is the file code of the index file. 
IPS is the page size in words. 


8=<3 DEO4 


The ISP DATA card 
a 8 16 


See naa 


ISP DATA. ~—s-FC=fc[, PAGESZ=DPS] [ , PAGEFIL=PF | 


where: fc is the file code of the data file. 
DPS is the page size in words. 
PF is the percent of the page to be used. 


The ISP RECORD card has the following format: 
1 8 16 
ISP RECORD RECSZ=RS, KEYSZ=KS| , KEYOFF=KF | 


where: RS is the size of the fixed length records in words. 
KS is the size of the key in BCD character units. 
KF is the offset of the key in BCD character units. 


An ISP ETC descriptor card can be used to continue any of these cards. 


Page Size 


Many factors enter into the determination of page size. Since a link! is 
divided into pages, the page size should be chosen to divide evenly’ into the 
link size (3840 words). If the file is composed of fixed length records, the 
page size should provide for minimum unused space by being the closest number to 
a multiple of the record size (including the two record control words) plus’7~ the 
page control word. 


However, since the page buffers are all the same size for INDEXED files, 
all INDEXED files should have the same page size for most efficient utilization 
of these buffers. Moreover, the page size can be altered from run to run to 
obtain better efficiency. Studies have shown that for random access small _ page 
sizes are most efficient and for sequential access larger pages are most 
efficient. 


Percent Fill 


The percent of the page to be used can also be altered from run to run. A 
percent less than 100 causes space to _ be reserved throughout’ the file. 
Subsequent adjustment of the percent fill allows records to be added in_ the 
previously unused space. Thus, if sufficient unused space is available on a 
page, records added to the file after its creation can be physically placed on 
the page to which they logically belong. 


en 


leor further background information, see Section IV of the File Management 
Supervisor manual. 
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Record and Key Parameters 


The record size (RS) of the largest record in the file must be given. 
Since a maximum of four ASCII characters can be contained in a word, the number 
of words per record is calculated by dividing the total number of ASCII 
characters in the record by four. 


number-of-ASClIl-characters 
CEIL 


RS = 2 


where: CEIL is the PL/I! truncating function that returns the smallest 
integer greater than or equal to its argument. 


The key size (KS) is determined by multiplying the number of ASCII 
characters in the key by a factor that expresses its length in BCD’ character 
units. 


Ses 
KS = number-of-ASClIl-characters-in-key * 6 


The offset is determined by multiplying the number of ASCII characters 
before the key by the same factor. If the offset is not given, an offset of 
zero is assumed. 


Memory Reservation 


Space must be provided for file tables and page buffers by a $ USE control 
card, as follows: 


T 8 16 
$ USE -ADUP LI? paXBUFZ/ 2/ 
where: n is the number of words required for the INDEXED files of a 


program. 


Each INDEXED file used requires a 160-word file table allocation. The page 
buffers are shared among all the INDEXED files of the program. An estimate of 
the number of words required can be obtained as follows: 


n = 8 + 160 * NF + MAX(1016, (MPS+4)*NPB) 


where: NF is the number of INDEXED files which are open. 
MPS is the maximum page size for all the INDEXED files. 
NPB is the number of page buffers needed. ISP requires that it be 
at least 3. 
MAX is the PL/I built-in function. 


PAGE BUFFERS 


A page buffer is an area of memory used to hold a page during processing. 
The number of page buffers allocated for a file affects the efficiency of 
operation. For example, the efficiency of direct access of an INDEXED file can 
be improved if there are sufficient page buffers to allow the fine index and the 
coarse index to be retained in memory. 
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The Utilization Report produced as a result of the execution of a_ program 
using INDEXED files can be used to determine the change in efficiency 
accomplished by the change in the number of page buffers allocated. The ratio 
of logical to physical reads and writes provides a good indication of the 
improvement. The Utilization Report for INDEXED files is described later in 
this section. 


Calculation of File Size 


The size of the data file and the index file can be calculated by the 
following methods. The number of links required for the data file and index 
file can be specified on the device assignment card for each file. A sample 
calculation of file size is given in the example following this section. 


The PL/I truncating functions FLOOR and CEIL are used in these formulas. 
These functions discard the fractional part of their arguments to produce an 
integer, as follows: 

FLOOR(R) is the largest integer < R 


CEILCR) is the smallest integer > R 


CALCULATION OF DATA FILE SIZE 


The formulas given here for calculation of the data file size use the 
following variables whose values are furnished by the user. 


NR = total number of records in the file 
RS = record size (in words) 

DPS = data page size (in words) 

PF = percent fill 


Values for the following variables are calculated using the given formulas. 


N1 = number of records that can be stored on the first page 
N2 = number of records that can be stored on each page after the first 
NDP = total number of data pages required 
NDL = number of 3840-word links required for the data file 
FLOOR DPS *« PF/100 - 65 
N1 = FLOOR RS + 2 


If NR + 1 < N11, only one data page is required. Otherwise, 


FLOOR DPS _* PF/100 oe! 
N2 = FLOOR RS 2 

NR_- Ni 
NDP = CEIL N2 +1 

NDP_* DPS 
NDL = CEIL 3840 
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CALCULATION OF INDEX FILE SIZE 


' \ The size of the index file is calculated using the following variables 
whose values are furnished by the user. 


NDP = number of data pages (from previous calculation) 
IPS = index page size (in words) 

KS = key size (in characters) 

KF = key offset (in characters) 


The values to be calculated are as follows: 


IEW = size of an index entry (in words) 

[1 = number of index entries stored on the first index page 

[2 = number of index entries stored on each page after the first 
NFP = number of fine index pages required 

NCP = number of coarse index pages required 

NIP = total number of index pages required 

NIL = number of 3840-word links required for the index file 


Se ae ee KE 
IEW = FLOOR 4 = FLOOR 4 a 


| Leo os 
11 = FLOOR IEW 


If NDP <¢ 11, then only one index page is required. Otherwise, 


LoS 
FLOOR | EW 


A) elas Bl Aaa fe 
o~ NFP CEIL IZ 5 ee | 


Since NFP > 1, one or more coarse index pages are required. 


NEP 3 2. = J 
FLOOR | 2 


NIP = NFP + NCP 


[PS_* NIP 
Ce tL 3840 


NO 
ll 


NCP 


NIL 


| 
gap3 DEOL 
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Example of INDEXED Fi A hmen 


The following fragment jllustrates the attachment of a file with INDEXED 
organization: 


- 8 16 

$ SNUMB 

$ IDENT 

$ OPTION PLI 

$ PL1 

IFA: PROC; 

Hel. OL FABLE: 
02 CODE PIc "9999", 
02 NAME CHAR(20), 
02 CONT CHAR(50), 
02 LAST CHAR(6); 
OPEN FILE(Z1) SEQUENTIAL OUTPUT; 
WRITE FILE(Z1) FROM( TABLE) KEYFROM( NAME) ; 
END; 

$ USE .XBUF1/1132/, .XBUF2/2/ 

$ EXECUTE 

$ FILE C1,A1S,1R,MSU0400 

$ FILE C2,A2S,1R,MSU0310 

$ DATA —s- Zz 

1SP INDEX FC=C1, PAGESZ=320 

ISP DATA FC=C2, PAGESZ=320, PAGEFIL=80 

ISP RECORD RECSZ=20, KEYSZ=30, KEYOFF=6 

$ ENDJOB - 

*** EOF 
DESCRIPTOR FILE CALCULATIONS 

In this example, a page size of 320 words with SO2 FIT1 1s specified. 
Therefore, only 256 words are used for record storage. The remaining 64 words 
on each page are reserved and can be used later for the addition of records to 
the file. 

The parameters of the ISP RECORD card are determined by examining the 
record TABLE. The record size in words (RS) is determined by adding the number 
of ASCII characters in the record TABLE and dividing by four to get the number 
of words required, as follows: 

number-of-ASCII-char rs 
RS = CEIL 4 
ib ot IQ & 50 45 80 
2 CELL 4 = CELL hu | = 20 
wd | 
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The key size in BCD character units (KS) is determined by taking the number of 
ASCII characters in the key and multiplying by a factor’. that expresses the 
length in BCD character units. Since a BCD character requires 6 bits and an 
ASCII character requires 9 bits, the calculation is: 


KS 


bits-per-ASCll-char 
no. Of ASCII chars in key *| bits-per-BCD-char 


to] 
KS = 20 Ara 30 


The offset in BCD character units (KF) is determined by multiplying by the same 
factor, the number of ASCII characters by which the key is offset from the start 
of the record, as follows: 


 bitsspar-asel char 


KF = no.-of-ASCII-chars- bits-per-BCD-char 
before-key 
9 
KF = 4& */6/= 6 


MEMORY RESERVATION CALCULATION 


The work region allocation is calculated, as follows: 


ios 160 * dot 0520 4 4) SS 11a2 


The $ USE control card, in this example, requests 1132 words for the use of 
INDEXED files. 


FILE SIZE CALCULATION 


Assuming the data file consists of 25 records, the size of the data file is 
calculated from the page size and percent fill as follows: 


FLOOR ZO: #80) = 5 | 


N1 = FLOOR ZU 2 
256 =- 65 
= FLOOR 22 
= 8 
256 - 1 
N2 = FLOOR 22 
= 11 
25 - 8 
NDP = CEIL 11 + 1 
>= 2 J 
= 3 
a ee AY 
NDL = CEIL 3840 
= ] 


One link is, therefore, specified for the data file on the device assignment 
card, as follows: 


$ FIle C2,A2S,1R,MSU0310 


B=i5 DEO4 


The size of the index file is calculated from the following set of 
formulas. The size of the index file page is taken to be the same as that of 
the data file page - 320 words. 


The size of the index file is calculated as follows: 


ho es F 4 
FLOOR k - FLOOR| 4 |+ 2 


IEW = 
a § = }.*+ 2 
= 6 
| 328 - a2 | 
11 = FLOOR 6 
= 2 


Since NDP < 11, only one index page is required. Therefore, 
ed See | 

CELL 3840 

1 


One link is, therefore, specified for the index file on the device assignment 
card, as follows: 


NEL 


$ PPLE C1,A1S,18; MSU90510 


UTILIZATION REPORT 


ee 


When a program using INDEXED files is executed, a utilization report is 
prepared and upon completion of the job, the report is printed. This report 
provides a record of the program's file access and contains information that can 
be used to improve the efficiency with which the INDEXED files are accessed. 


The utilization report for an INDEXED file has four columns containing 
information about the data file, information about the index file, file 
attributes, and job attributes. The following items are included in the 
utilization report. 
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LOGICAL READS 
LOGICAL WRITES 


PHYSICAL READS 


PHYSICAL WRITES 


PAGE SIZE 
PAGES ALLOCATED 


PAGES USED INITIALLY 


OVERFLOW PAGES USED 


TOTAL PAGES USED 
COARSE PAGES 
FINE PAGES 


MAXIMUM RECORD SIZE 


REY “SEZE 
KEY OFFSET 


COLLATING SEQUENCE 
ELPE ARP TA LZED 
FILE LAST UPDATED 


DELETED RECORDS 


OVERFLOW RECORDS 


TOTAL RECORDS 


BUFFER. SIZE 


NUMBER OF BUFFERS 


rele ACCESS 


This counter is incremented by one each time a 
READ statement is executed. 


This counter is incremented by one each time a 
WRITE, REWRITE, or DELETE statement is executed. 


This counter is incremented by one when a page is 
transferred from the external device to a page 
buffer. 


This counter is incremented by one when a page is 
transferred from a page buffer to the external 
device. 

The number of words in a page. 

The number of pages contained in the file. 


The number of pages actually used at 


initio lization. of the file, 

The number of pages, used for. the storage of 
records, beyond the last page used at file 
initialization. 


The sum of PAGES USED INITIALLY and OVERFLOW PAGES 
USED. 


The number of index file pages required for the 


coarse index. 


The number of index file pages required for the 


fine index. 
The number of words in the largest record. 


The number of characters in the key, expressed in 
BCD character units. 


The offset of the key from the beginning of the 


record in BCD character units. 

The collating sequence used for ordering keys. 
Date and time of initialization of the file. 
Date and time of the last update of the file. 


The number of deleted logical records currently in 
the file. 


The number of records written on overflow pages. 
This count includes active and deleted records. 


The number of records currently in the file. This 
count includes both active and deleted records. 


The number of words in the buffer page. The size 
of the buffer page is determined by the largest 
page of all INDEXED files used. 

The number of page buffers used by the program. 


The type of file activity. 


0 
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EXAMPLES OF INDEXED FILE ACCESS 


Figure 8-3 illustrates the creation of an INDEXED file. Data is taken from 
the system input file. The INDEXED file TABLE is opened for sequential output 
and records are written in the order of the key NAME. The utilization report 
produced from the execution of the job ts given tn Figure 8-4. 


The format of this utilization report is compressed for inclusion in_ the 
manual, but the information is not changed. The utilization report shows that 
eight logical writes were performed, corresponding to the eight input items. 
Since the page size was specified to be 320 words and one link was requested for 
the file, 12 pages are allocated for the file. The specification of the buffer 
allocation of 1780 words on the $ USE control card results in the allocation. of 


five buffers. 
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| 1 8 16 
| EE 


| $ SNUMB 
$ | DENT 
| $ OPTION PL1 
| $ PL1 LIST 


| IFC: PROC OPTIONS(MAIN) ; 
DCL TABLE RECORD FILE KEYED ENVIRONMENT( INDEXED); 
| DCL SYSIN FILE; 


DCL O1 PAYROLL, 


02 PLANT CHAR( 12), 
02 NUMBER CHAR( 8), 
02 NAME CHAR( 24), 


02 GROSSPAY PIG 22720 re 
02 DEDUCTIONS PIC"ZZ,ZZ7,722": 
ON ENDFILEC(SYSIN) GOTO EXIT; 
OPEN FILECTABLE) OUTPUT SEQUENTIAL TITLEC"AA"); 
LOOP: GET LIST(PLANT, NUMBER, NAME, GROSSPAY, DEDUCTIONS); 
WRITE FILECTABLE) FROM( PAYROLL) KEYFROM(NAME) ; 


GOTO LOOP; 
GAIT: CLOSE FILECTABLE); 
END; 
$ USE »XBUF1/1780/,.XBUF2/2/ 
$ EXECUTE 
$ LIMITS 10,50K,-2K 
$ FILE DX,A1S,1R,MSU0400,MSU0310 
$ FPLE [X,A2S,1R,MSU0400 
$ DATA AA 
or INDEX FC=1X,PAGESZ=320 


ISP DATA FC=DX, PAGESZ=320 

ie RECORD RECSZ=16, KEYSZ=36, KEYOFF=30 
$ DATA | * 

—— CLEVELAND 25067 JONAS 36367 7500 

| CLEVELAND 25068 JONSON 25163 5635 
CLEVELAND 25069 JUDD 14453 2336 
WASHINGTON 34567 KLAUS 1 0 

ALBANY 122269 MONTVALE 12263 2215 
CLEVELAND 25070 MOST 24567 5432 
CLEVELAND 3524 SMTH 44778 12343 
PHILADELPHIA 222233 TAYLOR 55569 23454 
$ ENDJOB 

***kEOF 


Figure 8-3, INDEXED File Creation 
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INDEXED Sequential 


Data File DX 


Logical Reads 
Logical Writes 
Physical Reads 
Physical Writes 

Page Size (Words) 
Pages Allocated 
Pages Used Initially 
Overflow Pages Used 
Total Pages Used 


IN 


Fr RO 
RPOrMON OC woo 


Coarse 


Total 


File Attributes 


Maximum Record Size (Words) 16 


Key Size (Characters) 
Key Offset (Characters) 
Collating Sequence 
File Initialized 


Buffer 
36 Number 


Processor Utilization Report 


Index File IX 


Physical Reads 
Physical Writes 
Page Size (Words) 
Pages Allocated 


Pages 


Fine Pages 
Pages Used 


Job Attributes 


Size (Words) 
of Buffers 


30 File Access 


6000 


01/16/75 14.54 


File Last Updated 01/16/75 14.54 


Deleted Records 
Overflow Records 
Total Records 


Figure 8-4. 


0 
0 
8 


Utilization Report for 


INDEXED File Creation 


320 


DEO4 


Figure 8-5 illustrates the access of the INDEXED file just created. 
Corrections to the spelling of two keys are taken from the system input file. 
The records with the correctly spelled key are written in the file and the 
records with the incorrectly spelled key are deleted from the file. The 


utilization report produced from the execution of this job is given in Figure 
8-6. 


The utilization report shows two logical reads corresponding to the two 
records entered under the incorrectly spelled key, and _ four logical writes, 


corresponding to the deletion of these two records and the addition of the two 
records under the correctly spelled key. Since all the records are on the same 


page, only one physical write and one physical read are necessary. 
1 8 16 
$ SNUMB 
$ IDENT 
$ OPTION PLI 
$ PL1 LIST 


LFA PROC OPTIONS(MAIN); 
DCL TABLE RECORD FILE KEYED ENVIRONMENT( INDEXED); 
DCL SYSIN- ELLE: 
DCL (WRONGNAME,RIGHTNAME) CHAR(24) ALIGNED; 
DCL 01 PAYROLL, 


02 PLANT CHAR( 12), 
02 NUMBER CHAR( 8), 
02 NAME CHAR( 24), 


02 GROSSPAY PIGTE LiL YL LL 5 
U2 DEDUCTIONS “PICVLZ 22 lyt2en 


ON ENDFILEC(SYSIN) GOTO EXIT; 
OPEN FILECTABLE) UPDATE DIRECT TITLEC"AA"); 
LOOP: GET LISTC(WRONGNAME,RIGHTNAME) ; 
READ FILECTABLE) INTO( PAYROLL) KEY(WRONGNAME); 
NAME = RIGHTNAME; 
WRITE FILECTABLE) FROM(PAYROLL) KEYFROM(RIGHTNAME) ; 
DELETE FILE(TABLE) KEY(WRONGNAME) ; 


GOTO LOOP; 
EAIT? CLOSE FILECTABLE): 
END; 
$ USE -XBUF1/2000/, .XBUF2/2/ 
$ EXECUTE 
$ LIMITS ~10,50K,=2K 
$ PLE DX,A1S,1R,MSU0310,MSU0400 
$ FELE ix, AZS,1R,DSS270 
$ DATA AA 
ISP INDEX FC=1X, PAGESZ=320 


ISP DATA FC=DX, PAGESZ=320 
ISP RECORD RECSZ=16,KEYSZ=36, KEYOFF=30 


$ DATA | * 
JONAS JONES 

SMTH SMITH 

$ ENDJOB 


** * EOF 


Figure 8-5, INDEXED File Access 


8-21 DEO4 


INDEXED Sequential 


Data File DX 


Logical Reads 
Logical Writes 
Physical Reads 
Physical Writes 

Page Size (Words) 
Pages Allocated 
Pages Used Initially 
Overflow Pages Used 
Total Pages Used 


WN 


m NO 
FPOrPNORHSE bh 


File Attributes 


Maximum Record Size (Words) 16 
Key Size (Characters) 36 
Key Offset (Characters) 30 
Collating Sequence 
File Initialized 01/16/75 14.54 
File bast Updated 01/16/75 14.55 
Deleted Records 2 
Overflow Records 0 
Total Records 10 


Figure 8-6. 
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Physical Writes 
Page Size (Words) 
Pages Allocated 
Coarse Pages 

Fine Pages 
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320 


320 
5 
Update 


DEO4 


SECTION: {Xx 
REGIONAL ORGANIZATION 
This section describes the structure of files with REGIONAL organization. 
The method of attachment for REGIONAL files and the utilization report produced 


aS a result of accessing a REGIONAL file are given. Finally, examples of the 
creation and access of a REGIONAL file are included. 


REGIONAL files are processed by the Regional Sequential Processor (RSP) in 
the PL/I system. 


REGIONAL FILE ACCESS 


A file with REGIONAL organization consists of a number of regions, 
corresponding to the fixed length logical records of the file. REGIONAL files 
can be assigned only to direct access devices. 


A record in a REGIONAL file does not have an imbedded key; instead, the 
source key on the data transmission statement indicates the region. Since the 
regions of the file correspond one-to-one to the logical records of the file, 
the source key specifies the position of the record within the file. The source 
key is a character string consisting of a maximum of 32 characters representing 
a positive integer value, 


File Creation 


A REGIONAL file can be generated either in sequential or direct mode. When 
the REGIONAL file is generated sequentially, the source keys must be given in 
ascending order if the KEYFROM option is specified on the data transmission 
Statement. When the values of the source keys skip some integers, the omitted 
regions are filled with dummy records. For example, if source keys 1, 2, 4, 
6, «2. are specified, regions 3, 5, ... are filled with dummy records. When the 
file is closed, any remaining records are filled with dummy records. 


When the file is created directly, all regions are filled with dummy 
records upon opening the file. Then the records are inserted in the regions 
specified by the value of the source key on the data transmission statement. 


A dummy record contains an identifying code in the first word. The dummy 
record code can be specified on a control card at execution time. If the dummy 
record code is not specified, the octal number '177000000000' is used. 
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File Access 


Once a file is created, it can be accessed either in sequential or direct 
mode. Each record retrieved should be checked to determine whether it is a data 
record or a dummy record. 


SEQUENTIAL ACCESS 


A SEQUENTIAL file can be opened with either the INPUT or UPDATE attribute. 
The data transmission statement cannot contain the KEY option, but the KEYTO 
option can be used; thus the file can have the KEYED attribute. 


Records are retrieved in the order of ascending region number. Actual and 
dummy records are retrieved sequentially. 


In SEQUENTIAL UPDATE, the execution of a REWRITE statement results in the 
replacement of the record retrieved by the READ statement (with the SET option, 
if the file has the UNBUFFERED attribute). The execution of a DELETE statement 
causes the most recently retrieved record to be replaced by a dummy record. 


DIRECT ACCESS 


The data transmission statement for direct access must include the KEY 
option to specify the region to be accessed. A new record is written in_ the 
region corresponding to the key value by the execution of a WRITE statement. 
The execution of a DELETE statement causes a dummy record to be written in the 
specified region. 


No record checks are made by the system to determine whether the record 
being written over is an actual or dummy record. r= ¥S the user's 
responsibility to maintain the integrity of the file by checking the record code 
systematically. 


Data Transmission Statements for REGIONAL Files 


Table 9-1 lists the data transmission statements that can be used with 
REGIONAL files. 
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Table 9-1. Data Transmission Statements for REGIONAL Files 


SEQUENTIAL OUTPUT 


WRITE FILECfile-name) FROM(variable-name) [ KEYFROM(expression)] ; 


LOCATE based-var FILE(file-name) [ KEYFROM( expression] [ SET(pointer-var) ] ; 


SEQUENTIAL INPUT 


INTO( variable-name) KEY( expression) 
READ FILE(file-name) ; E 
SET(pointer-var) KEYTO(char-strng-var) 


READ FILE(file-name) IGNORE( expression); 
SEQUENTIAL UPDATE 
INTO(variable-name) KEY (expression) 

READ FILE(file-name) ; 
SET(Cpointer-var) KEYTO(char-strng-var) 


READ FILE(file-name) IGNORE( expression); 


REWRITE FILE(file-name) ; 


DELETE FILE(file-name) ; 


DIRECT OUTPUT 


WRITE FILECfile-name) FROM(variable-name) KEYFROM(expression) 3; 


DIRECT INPUT 


READ FILE(file-name) INTO(variable-name) KEY(expression) ; 
DIRECT UPDATE 


READ FILE(file-name) INTO(variable-name) KEY(expression) ; 


REWRITE FILE(file-name) FROM(variable-name) KEY(expression) ; 


WRITE FILEC(file-name) FROM(variable-name) KEYFROM(Cexpression) ; 


DELETE FILE(file-name) KEY(expression) ; 
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STRUCTURE OF A REGIONAL FILE 


A REGIONAL file consists of a number of 320-word buffers, each of which 
contains at least one whole record; i.e., the maximum allowable record size is 
320 words. As many records as can be fully contained will be placed ina single 
buffer, and when the remaining buffer space is less than the record size, the 
next record will be placed in the next buffer. 


Figure 9-1 illustrates the structure of a REGIONAL file. This file was 
created using the default octal pattern for a dummy record and specifying keys 
of 2, 3, and &. The first region of the file and the regions after region 4 are 
all. filled with dummy records. The record size for this example is 100 words. 
Therefore, three records can be contained in each buffer and twenty words at the 
end of each buffer are unused. 
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buffer 1 


177000000000 


unused space 


buffer 2 


177000000000 


region #1 


region #2 


region #3 


region #4 


dummy record region #5 


177000000000 


dummy record 


region #6 


Figure 9-1. Structure of a REGIONAL File 


ae DEO4 


ATTACHMENT OF A REGIONAL FILE 
To specify and attach a REGIONAL file, the following requirements must _ be 
met: 
® The file must be designated as REGIONAL. The REGIONAL keyword can be 
specified in the ENVIRONMENT attribute at compile time, or, if no 
ENVIRONMENT attribute is given, a descriptor file containing RSP cards 


can be supplied at execution time. 


® A descriptor file must be provided to specify the file code and _ the 
size of the fixed length record. 


) A device assignment control card for a direct access device must be 
provided for the file. 


re The size of the work region to be reserved for REGIONAL files must. be 
specified by $ USE control card. 


Descriptor File for REGIONAL Fil 


A file with REGIONAL organization has two types of cards associated with 
it, namely: the RSP DATA card and the RSP RECORD card. The format of these _ two 
cards is as follows: 

1 8 16 

RSP DATA FC=fc 

RSP RECORD RECSZ=n [, DBI T=d] 

where: fc is the two character alphanumeric code identifying the file. 

n is the number of words in the fixed length record. 


d is the octal dummy record pattern. If d is given, it must be a 
12 digit octal value. 


If the dummy record pattern is not given, the pattern '177000000000!' is assumed. 


Memory Reservation 


Space must be provided for file control blocks and buffers by an 
appropriate $ USE control card, as follows: 


$ USE «RBUF1/n/,.RBUFZ/2/ 


where: n is the number of words required for the REGIONAL files of a 
program. 


Each REGIONAL file requires a 400 word allocation. An estimate of the number of 
words needed can be obtained as follows: 


n = 400 * F 


where: F is the maximum number of REGIONAL files open at one time. 
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The work region allocation is shared among the REGIONAL files. When only one 
file is open, the remaining words in the allocation can be used as buffer space. 
The opening of a second file subtracts 400 words from the area that can be used 
for buffers, and so on. When a file is closed, its 400 word allocation is 
released. 


Calculation of File Size 


To determine the number of links required for a REGIONAL file, the number 
of records per 320-word buffer is calculated; then the number of buffers 
required for the file is calculated on the basis of the total number of records 
in the file; finally, the number of links required is determined by dividing the 
number of buffers required by the number of buffers per link, as follows: 


320 
records-per-buffer = FLOOR femererrer ] 


records-in-file 
buffers-per-file = CEIL records-per-buffer 
buffers-per-file 
links-required = CETL 12 


Example of REGIONAL File Attachment 


The following fragment illustrates the attachment of a file with REGIONAL 
Organization: 
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SNUMB 

IDENT 

USERID XXXXXX$XXXXXX 
OPTION PL1 

ate) 


HAHAHAHA SH 


EXD: PROC 


OPEN FILECF2) UPDATE TITLEC'Y1") ‘RECORD 


$ USE »RBUF1/2000/, .RBUF2/2/ 
$ EXECUTE 
$ PRMFL ag eae 


$ DATA 1 
RSP FC=B1 
RSP RECSZ=40 


$ ENDJOB 


The $ USERID control card contains the system master catalog name and _ the 
log-on password. A $ USERID control card must be included in the deck if a 
$ PRMFL card is used. The USERID control card prevents unauthorized use of the 
system resources. 
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UTILIZATION REPORT 


When a program using REGIONAL files is executed, a utilization report is 
prepared and upon completion of the job, the report is printed. The following 
items are included in the utilization report: 


LOGICAL READS This counter is incremented by one each time a READ 
statement is executed. 


LOGICAL WRITES This counter is incremented by one each time a 
WRITE, REWRITE, or DELETE statement is executed. 
This count includes the dummy records automatically 


written. 

PHYSICAL READS This counter is incremented by one when a page is 
transferred from the external device to a page 
buffer. 

PHYSICAL WRITES This counter is incremented by one when a page is 
transferred from a page buffer to an external 
device. 

DUMMY WRITES This counter is incremented by one whenever a dummy 


record is written. The number of dummy-~ records 
automatically written is included in this count. 


ACTUAL RECORDS MAX The maximum region number actually used in a data 
transmission statement is given. 

PELE: LIMIT The number of records in the file is given. 

BUFFERS USED This counter is incremented by one each time = any 
page is transferred into a buffer for access to its 
records. 

BUFFER SIZE MAX The number of words in a buffer is given. 

DUMMY RECORD OCT. The pattern used as the first word of a record to 


indicate a dummy record is given in octal. 


EXAMPLES OF REGIONAL FILE ACCESS 


Figure 9-2 illustrates the creation of a REGIONAL file. The file is 
created in direct mode, so upon opening the file, the file is filled with dummy 
records. The utilization report produced from the execution of this job is 
given in Figure 9-3. 


The utilization report shows that the file consists of 80 records. This 
number results from the record size (20 words) and the fact that the permanent 
data file SAMPLE/REGION has a maximum size of 5 blocks (1600 words) of mass 
storage space reserved for it as a result of a previous FILSYS activity (refer 


to the File Management Supervisor). 


Opening the file causes 80 dummy records to be written, then 11 actual data 
records are written in the program. The number of logical writes is, therefore, 
91. 
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The number of buffers used (12) includes 5 buffers used to write the 80 
dummy records plus 7 buffers used as a result of the WRITE statement executions. 
The number of buffers used in the latter case is determined by the amount of 
buffer space in memory, the input sequence of keyed records, and the algorithm 
used by the REGIONAL processor for determining which buffer in memory (if there 
are more than one) will be overwritten when none contains the referenced record. 
In this example the amount of buffer space is 800 words, allowing for 2 buffers 
in memory. When neither contains the referenced record for a given WRITE 
statement execution, the algorithm turns out the least recently accessed buffer 
to bring in the needed page. 
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SNUMB 
IDENT 


OPTION PLI 


$ 
> 
$ USERID XXXXXX$XXXXXX 
$ 
$ 


FEL LIST 


RFC: PROC OPTIONS(MAIN); 


DCL “PUOL. -F 
DCL SYSIN 


[LE RECORD KEYED ENVIRONMENTCREGIONAL); 
FILE; 


DCL O1 REC, 
02 ORDER CHAR(32), 


02 


IMAGE CHAR(48); 


ON ENDFILECSYSIN) GOTO EXIT; 


OPEN FILE( 
IN: GET LEST(O 


POOL) OUTPUT DIRECT TITLEC"YY"); 
RDER, IMAGE); 


WRITE FILE(POOL) FROMC(REC) KEYFROMCORDER) ; 


GOTO IN; 


EXITs CLOSE FPELECPOOL?; 


END; 


EXECUTE 
LIMITS Sy 


ARASH 49 


DATA F 


USE »RBUF1/800/, .RBUF2/2/ 


S5K,°24K 


PRMFL RX,W,R,SAMPLE/REGION 


RSP DATA —- FC=RX 
RSP RECORD RECSZ=20 


$ DATA | * 
39 UPHAM 

22 ESSEA 

LZ ROWE 

45 BELLEVUE 

6 STRATFORD 

10 ORIENT 

Zi LEBANON 

42 PORTER 

34 ARDSMOOR 

5 WASHINGTON 
8 AP ELS DE 

$ ENDJOB 

*k** EOF 


Figure 9-2. REGIONAL File Creation 


RSP Utilization Report 


Data File RX 


Logical Reads 0 
Logical Writes 91 
Physical Reads 12 
Physical Writes iZ 
Dummy Writes 80 
Actual Records Max 45 
File Limit 80 
Buffers Used 12 
Buffer Size Max 320 
Dummy Record Oct. 177000000000 
Figure 9-3. Utilization Report for REGIONAL File Creation 
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Figure 9-4 illustrates the access of the REGIONAL file just created. The 
utilization report produced as a result of the execution of this job is given in 
Figure 9-5, 


The input data causes the records with keys 22 and 6 to be changed, the 
records with keys 34 and 10 to be deleted, and the record with key 7 to be 
added. The utilization report indicated that five logical writes were 
performed, one for each input item. Of these five logical writes, two writes 
were dummy writes since the deletion of a record in a REGIONAL file involves 
writing a dummy record. Three physical reads and physical writes were necessary 
since records 6, 7, and 10 are located in buffer #1, record #22 is located in 
buffer #2, and record #34 jis located in buffer #3. 
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$ SNUMB 

$ | DENT 

$ HSERID XXXXXXSXKXKXX 
$ OPTION PLI1 

$ PL1 LIST 


RFA: PROC OPTIONS(MAIN); 
DCL POOL FILE RECORD KEYED ENVIRONMENTCREGIONAL) ; 
DCL Os: (REC; 
02 ORDER CHAR(32), 
02 IMAGE CHAR(48); 
ON ENDFILECSYSIN) GOTO EXIT; 


OPEN FILE(POOL) UPDATE DIRECT TITLE ("YY"); 
LOOP: GET LISTCORDER, IMAGE) ; 
IF IMAGE = '*' THEN DELETE FILE(POOL) KEYCORDER); 
ELSE REWRITE FILE(POOL) FROM(REC) KEYCORDER); 


GOTO LOOP; 
EXIT: ‘GLOSE FIEECPOOL?: 

END; 
$ USE »~RBUF1/400/,.RBUF2/2/ 
$ EXECUTE 
$ LIMETS. 5S) 53K, 3°2% 
$ PRMFL RX,W,R,SAMPLE/REGION 
$ DATA si i 


RSP DATA FC=RX 
RSP RECORD RECSZ=20 


$ DATA | * 
22 GLOUCESTER 
34 * 
6 AVON 
Zz HOLLAND 
10 * 
ENDJOB 
**x* EOF 


Figure 9-4. REGIONAL File Access 
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RSP Utilization Report 


Logical Reads 
Logical Writes 
Physical Reads 
Physical Writes 
Dummy Writes 
Actual Records Max 
File Limit 

Buffers Used 
Buffer Size Max 
Dummy Record Oct. 


Figure 9-5, 


Utilization Report for REGIONAL File Access 


Data File RX 


320 
177000000000 
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SECTION X 


LINKING PL/!| AND OTHER LANGUAGES 


This section describes the mechanism for linking PL/I programs and programs 
written in other languages. The format and contents of the argument list = are 
described. 


Data can be shared between programs written in PL/I and programs written in 
other languages, provided the format and mapping of a PL/I data type is 
equivalent to the format and mapping of a data type in the other language. PL/I 


has a large number of data types; usually, a subset of these data types is 
available in another language. The internal representation for each PL/I data 
type is given in the next section of this manual. The information there = and 


below applies both to data content of RECORD 1/0 files and arguments passed via 
CALL to subprograms. 


Equivalent Data Representations 


The following pairs of data declarations describe equivalent’ storage 
representations in Series 60 PL/I and COBOL-68. 


COBOL-68 PuLi 

O1 A PIC 9(8) COMP=T1. DEL FIXED BINGSS) 
OLB PIC. 9C18) COMP=1. DCL. B FLXAED..BINCIT 3 

Ol -C.-P1G 916). COMP=2. DCL G FLOAT BING2Z/ 2) 

Ob. D PIC Sts) COMP=2 « Dl. D FLOAT .BINt 63 }> 

PE VE PILE -SCLO) COMPS. DEL E-FIRED Bi s5 33 

O01 A OCCURS 2 TIMES. DCL O01 AC2) ALIGNED, 
O2,-B OGCURS 3 TIMES, 02.-B(3), 

03. C- OCCURS 4. TIMES. 02. Clas: 

Oe X- PAL Ot 7 COMP s2 Ob % PIXED BINCS523 
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The following pairs of data declarations describe equivalent storage 
representation in Series 60 PL/I and FORTRAN. 


FORTRAN Pus i 
INTEGER A DCL A FIXED BINCS5); 
REAL B Tew" DCU EB -ELOA] SINGZ7 23 
DOUBLE PRECISION C CL GC - ELOAT -BINC635 75 
COMPLEX D DCL D COMPLEX FLOAT BINC27);3 
CHAR#n E DCL E CHAR(n) ALIGNED; 


Note that n must be less than or equal to 511 in FORTRAN and must be less 
than or equal to 256 in PL/I if the variable is involved in an_— Input/Output 
statement or requires conversion. Also, since PL/I character data is ASCII 
strings in 9-bit bytes, the FORTRAN program called by PL/I must be compiled in 
the ASCII mode. 


The following pairs of data declarations describe equivalent storage 
representations in Series 60 PL/I and COBOL-74. 


COBOL-74 Piss 

O01 A COMP-6. DCE A FEXED BIN(35); 
Of 6 PIC S9sSVs9 DCL B CHAR(6); 

SIGN LEADING SEPARATE. 
Oi € PIC XCIO). DCL C CHAR(10); 
01 D OCCURS 2 TIMES. DCL 01 D(2) ALIGNED, 
O02 E OCCURS 3 TIMES. G2 ES Fy 
03 F OCCURS 4 TIMES. ie an ok oe ee 
04 G COMP-6. 04 G FIXED BIN(35); 


Note that a future version of PL/I is expected to have a DECIMAL arithmetic 
format compatible with COBOL-74 COMPUTATIONAL data but incompatible with the 
present PL/I DECIMAL representation. The future form will use the packed 
decimal hardware format. 


INTERFACE 


When a PL/I program calls a program written in another language, the called 
program is responsible for saving any index registers used by PL/I programs and 
restoring these index registers when control is returned to the PL/I calling 
program. The argument list and return address are transmitted to the called 
program by index registers. The following index registers are involved: 


Index register 6 contains the starting address of the argument Fists 


Index register 1 contains the return address to be used for normal return 
to the PL/I! program. 


Index register 2 contains the current stack frame header address and must 


be saved by the called program and restored before return to the PL/I 
calling program. 
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The argument list contains a control word, followed by an entry for each 
argument. If any of the arguments has a variable length dimension (or, if the 
OPTIONS (VARIABLE) attribute is used in the procedure declaration), an 
additional entry is made for every argument in the list. The argument list has 
the following format: 


where: n indicates the number of arguments in binary fixed point. 


m indicates the number of arguments in binary fixed point if 
descriptors are required. 


arg-| is a pointer value indicating the address of the i-th 
argument. If the argument has a bit offset, the offset 
Valte occupies the Teast significant bits of Bits 18 
throuen 73. 


desc-i is a pointer value indicating the address of the _ i-th 
descriptor. The bit offset of this pointer value is always 
zero since argument descriptors begin on a word boundary. 


If none of the arguments requires a descriptor, m is zero, If the called 


procedure does not have any arguments, index register 6 contains the address of 
a word containing zero, 
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Argument Descriptor 


An argument descriptor contains information about the transferred arguments 
in the following format: 


TYPE 


indicates the data type of the arguments. 
indicates the packing status of the argument, as follows: 


indicates the argument is packed. 


P=1 
P=0 indicates the argument is unpacked. 


gives the number of dimensions in an array. The array bounds 
and multipliers follow the base descriptors. 


gives the size. 


The data type of the argument is indicated by a code, The code values and 
their interpretations are as follows: 


Data Type 


Code 
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Data Type 


Real binary fixed single precision 
Real binary fixed double precision 
Real binary float single precision 
Real binary float double precision 
Complex binary fixed single precision 
Complex binary fixed double precision 
Complex binary float single precision 
Complex binary float double precision 
Real decimal fixed 

Real decimal float 

Complex decimal fixed 

Complex decimal float 

Pointer 

Offset 

Label 

Entry 

Structure 

Area 

Bit string 

Varying bit string 

Character string 

Varying character string 

File 
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DIMENSIONS IN AN ARRAY 


The array bounds and multipliers follow 


f ‘ argument, as follows: 


a> 


it is 


OEE 


upon 


2 
upper bound-m 
multiplier-m 


lower bound-1 
J upper bound=t 
pomieipiierst 


the descriptor for the array 


informati 


on 


for the m-th 


(rightmos 
dimension 


informati 
for the f 
(leftmost 
dimension 


When the array elements are packed, the multiplier 


in words, 


The size field in the descriptor gives the following 


the argument type: 


t) 


on 
iyst 


) 


is in bits; otherwise, 


information depending 


string - the number of bits or characters, 
area - the number of words. 
structure - the number of elements in the structure, 


arithmetic 


value, 


105 


the scale in the leftmost 12 bits and 


PeSentwest <2 Bits. The scale is a 


the precision in the 
two's complement signed 
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EXAMPLE 


The following PL/I program calls two external procedures, as follows: 


P1: PROC; : 
~ DCL X FIXED; ww 
DCL D FIXED DECIMAL; 
cL BL BITC, 
B2 BIT(2); 
BCL 01. S, 
02 B(S5) UNALIGNED, 
03 C FIXED, 
03 D2 FIXED, 
02 A DECIMAL; 
DCL SUB1 ENTRY(FIXED,FIXED DECIMAL,BIT(1),FIXED UNALIGNED); 
DCL SUB2 ENTRY(FIXED,1,2(*) UNALIGNED,3 FIXED,3 FIXED,2 DECIMAL); 
CALL SUBIUX, 081,025 y 
CALL SUB2(X,S); 
END; 


The object program produced for Pl includes procedure calls to SUB1 and 
SUB Zs Before the transfer, index register 6 is set to point to the argument 
list. The procedures SUB1 and SUB2 must save index register 2 and restore it 
upon return. The argument lists for the two procedures are as follows: 


Argument List for SUB1L: 
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and the argument descriptors are as follows: 


descriptor for 


descriptor for 


descriptor for 


lower bound of 


upper bound of 


multiplier for 


descriptor for 


lower bound of 


upper bound of 


multiplier for 


descriptor for 


lower bound of 


upper bound of 


multiplier for 


D2 


D2 


D2 


D2 


descriptor for A 


The descriptor for a structure is immediately followed by the descriptors for 


each of its members. Also notice that the 


members 


of dimensioned 


contain copies of the bounds of the containing structure, 
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OPTIONS ATTRIBUTE 


The OPTIONS attribute can be used to generate standard calling sequences 
for programs written in GMAP, COBOL, or FORTRAN, For example, consider’ the 
following program, which calls external procedures written in PL/!I, GMAP, COBOL, 
and FORTRAN: 


Pl: PROC OPTIONS(MAIN); 

DCL X1 FIXED STATIC: oe 

DCL Fl FLOAT EXTERNAL; 

DCL D1 FIXED DECIMAL EXTERNAL; 

DCL CF1 COMPLEX FLOAT: p— 

DCL. BE BITCT) 

DCL B2-81TC23- 

DCL B3 BIT(3) ALIGNED STATIC; 

DCL C1 CHAR(1) EXTERNAL; ~— 

DCL PSUB ENTRY(FIXED,FIXED DECIMAL,BIT(1),BIT(2)); 

DCL GSUB ENTRY(FIXED,BIT(3) ALIGNED) 
OPTIONS(GMAP); 

DCL CSUB ENTRY(FIXED,FLOAT,FIXED DECIMAL, CHAR(1)) 


OPTIONS( COBOL) ; 
DCL FSUB ENTRYCFIXED, FLOAT, COMPLEX -PLOAT, CHARC1)3 
OPTIONS( FORTRAN) ; 7 


CALE -PSUBCX1;,D1, 61,82); 


CALL. GSUB( AT, BS.) 


CALL CSUBCKI, Fi, 01,6133 


CALL. PSUBCXT Fi, eri, 0133 


END; 


Two different calling sequences can be generated for a procedure call to an 
entry declared with the OPTIONS attribute specifying GMAP, COBOL or FORTRAN. 
The simplest is possible only if the referenced arguments have the attribute 
STATIC and have no execution time location variability such as nonconstant 
subscripts. In such cases the code is: 


TSkek entryname 

TRA eat a 

ARG 0 

ARG arg-l 

ARG are-2 

ARG arg-n 

When any argument fails to meet the above criteria, a normal PL/I calling 
sequence is generated, In this second case, an argument list is built as usual 
and a PL/I! procedure call is made to a run-time support routine. The support 


routine then builds a calling sequence similar to that above, executes it, and, 
upon regaining control, returns through the normal PL/I mechanism. 
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CALL 


CALL 


CALL 


CALL 


The four code generation cases 


PSUB 


EAQ 
STQ 
EAQ 
STQ 
EAQ 
STQ 
EAQ 
STQ 
LDQ 
STQ 
EAX6 
TSXLP 


GSUB 


TSXLP 
TRA 
ARG 
ARG 
ARG 


CSUB 


TSXLP 
TRA 
ARG 
ARG 
ARG 
ARG 
ARG 


FSUB 


EAQ 
STQ 
EAQ 
oD 
EAQ 
S10 
EAQ 
is He 
LDQ 
STQ 
EAXBP 
EAX6 
TSXLP 


~STATICO 


GSUB 
4,1C 

0 
~STATICO 
~STATICI 


CSUB 
6,1C 

0 
~STATICO 
Fl 

D1 

Ci 


~STATICO 
L1g5P 


illustrated in the sample program above are: 


Normal PL/I! procedure 


Xl in internal static storage 


External 


reference 


Bl in automatic storage 


B2 in automatic storage 


There are 


External 


four arguments 


reference 


Inline subroutine call 


External 


X1 
B3 


reference 


Inline subroutine call 


External 


KE 

External 
External 
External 


Dynamically built subroutine call 


X1 
External 
CPi tn au 
External 
Number of 
External 


Set arg-| 
GMAP-CALL 


reference 


reference 
reference 
reference 


reference 
tomatic storage 
reference 
arguments 


reference 
ist pointer 
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SECTION XI 


INTERNAL REPRESENTATION OF PL/I DATA 


To discuss the positioning of variables in storage, it is necessary to make 
a distinction between major variables and member variables. A major variable is 
either a level 01 structure or a variable not contained within a structure. A 
member variable is a variable contained within a structure. A major variable is 
positioned at a word or even-word boundary depending on its data type. <A member 
variable is positioned at a bit, byte, word, or even-word boundary depending on 
its data type and alignment. 


RIABLES 


Each PL/!I variable has a data type, an aggregate type, and an alignment 
type. The data type and the aggregate type determine the values that can be 
accommodated by a storage unit. The alignment type affects the way in which the 
variable is laid out in storage. 


Alignment 


Every variable has an alignment attribute. An ALIGNED variable is. stored 
for convenient access and an UNALIGNED variable is stored for conservation of 
storage. 


If the alignment attribute is not declared for a variable, the variable 
acquires this attribute in the following way: 


2 If the variable is contained in a structure with an explicitly 
declared alignment attribute, the variable acquires the alignment 
attribute of the smallest containing structure with an explicit 
alignment declaration. For example, in the following structure: 


DEL Wiss, 
02 $2 ALIGNED, 
03 Bl BIT(2), 
03 $3 UNAL, 
Oh B2 BIT(3), 
03 B3 BIT(4), 
02 Bh BIT(S5); 


Bl acquires the alignment attribute of $2, namely: ALIGNED. 
B2 acquires the alignment attribute of $3, namely: UNALIGNED. 
B3 acquires the alignment attribute of $2, namely: ALIGNED. 
Bh remains unresolved, 
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& If the alignment of a variable cannot be resolved by the explicit 
declaration of containing structures, the alignment is determined by 
the variable's data type. A nonvarying string scalar or a_ structure 
acquires the UNALIGNED attribute. All other variables acquires the 
ALIGNED attribute. The following list indicates the default 
assumption made for an unresolved variable: 


UNALIGNED ALIGNED 
nonvarying string variables varying string variables 
structures arithmetic variables 


address variables 
area variables 
arrays 


Representation 


There are four units available for the representation of data, namely: 
bits, bytes, words, and double-words. The characteristics of the data _ type 
determine the minimum unit that can be used to represent it. The following list 
indicates the minimum units for some data types: 


Minimum 
Data Type eh 
binary arithmetic bit 
bit strings 
decimal arithmetic byte 
character strings 
varying strings word 
file, entry, and label 
complex arithmetic double-word 


The unit of representation determines the boundary requirement of the 
variable in memory. For example, a decimal number starts and ends on a byte 
boundary. 


Positioning in Memory 


A variable can be positioned in memory either to facilitate its access or 
to conserve storage. A frequently accessed variable should be positioned by’ the 
user at a word or even-word boundary and occupy an integral number of words. An 
infrequently-accessed variable should be positioned at its minimum unit boundary 
and occupy only the storage necessary for its representation. 


The compiler assumes that a major variable is frequently accessed and 
therefore, positions it at a word boundary independent of its alignment 
attripure; Furthermore, a major variable that is an external or a double 
precision binary arithmetic variable is positioned at an even-word boundary. 
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The positioning of a member scalar variable depends upon its data type and 
its alignment. All ALIGNED scalar variables are positioned at a word or 


even-word boundary. UNALIGNED scalar variables are positioned at the boundary 
determined by their data type. 


The positioning of a member aggregate variable depends upon the maximum 
unit of representation of its components and its alignment. ALIGNED aggregates 
are positioned at a word or even word boundary. UNALIGNED member aggregates are 
positioned at the maximum unit of representation of their components. For 
example, an UNALIGNED member aggregate consisting of UNALIGNED bit’ strings 
Starts at a bit boundary and occupies only as many bits as necessary to 
represent its contents. However, an UNALIGNED member aggregate consisting of 
UNALIGNED bit and character strings starts at a byte boundary and occupies 
enough bytes to represent its contents. 


A more detailed discussion of the positioning of member variables is given 
in the second half of this section. 


Supplementary storage 


When a variable is positioned for efficient access, it sometimes occupies 
more storage than is necessary for its representation. This additional storage 
is called supplementary storage. The supplementary storage is used in 
conjunction with the minimum storage required for the variable to permit a 
larger and more convenient representation of the stored value. For example, the 
value is stored for whole word referencing and no shifting or masking is 
required, 


Filler Storage 


The positioning of variables can create unused space, When the unit of 
representation of two adjacent variables is different, filler storage is often 


required, For example, a variable represented in bits can be followed in memory 
by a variable represented in bytes. If the last bit occupied by the first 
variable is not the tlast bit of a byte, the bits between the last bit of the 
variable and the first bit of the next byte are filler storage. Filler storage 
is never allocated at the beginning of a variable. 


Filler storage is also created by alignment requirements. For example, an 
ALIGNED complex number followed by an UNALIGNED bit string’ contains 12 bit 
followed by another ALIGNED complex number results in 71 bits of filler storage, 


Grouping variables with the same unit of representation and alignment 
minimizes the amount of filler storage allocated, Filler storage within = an 
array is especially costly since the unused space occurs within each element of 
the array, 
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Packed Property 


The terms packed and unpacked are applied to variables’ to describe their 
internal representation. A scalar variable is said to be packed if it is 
positioned at a boundary determined by its minimum unit of representation = and 
occupies only enough of those units to represent its value. A scalar variable 
is said to be unpacked if it is positioned at a boundary greater’ than its 
minimum unit of representation. 


An arithmetic, nonvarying string, or pointer variable that is declared 
UNALIGNED is packed. An aggregate variable that is declared UNALIGNED = and 
contains only packed variables is packed. 


The symbol table listing gives the alignment attribute and packed property 
for every member variable. 


STORAGE LAYOUT RULES FOR PL/| MEMBER VARIABLES 


Exact rules for the layout of a member variable in the 36-bit, h-byte words 
of memory are given here. The rules assume that the starting layout address’ of 
the variable is the terminating word and bit address of the immediately 
preceding structure member (the bit offset for the first member of a level 
structure is 0). The rules are given for scalar variables, then for structure 
variables, and finally for array variables. 


Storage Layout for Member Scalars 


To determine the storage layout for a given scalar variable at a given word 
and bit address, proceed as follows: 


i; Begin the layout at the given address. 


2% Use Table 11-1 to determine the required boundary for the variable. 
If the starting address is not at a boundary of the required type, 


then lay out filler storage up to the next boundary of the required 
type. 


os Use Table 11-1 to determine the minimum storage for the variable. Add 
the specified amount of storage to the layout. 


4, If the layout does not end at a boundary of the required type (as 
determined in Step 2), then lay out supplementary storage up to the 
next boundary of the required type. 
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Table 11-1. Boundary and Length for Scalar Variables 


Data Type 


REAL FIXED BINARY(p,q) 
SO ae es eee 
56 4p 1 
REAL FIXED DECIMAL(p,q) 
REAL FLOAT BINARY(p) 
1) oO A ee 
26x p< Gs 


REAL FLOAT DECIMAL(p) 


COMPLEX FIXED BINARY(p,q) 
COMPLEX FIXED DECIMAL(p,q) 
COMPLEX FLOAT BINARY(Cp) 
COMPLEX FLOAT DECIMAL(p) 
CHARACTER 
NONVARYING 
VARYING 
Bt 
NONVARYING 
VARYING 
PICTURE '"P"' (with related 
data type CHAR(n)) 
LABEL 
ENTRY 
FORMAT 
POINTER 
OFFSET 


rULE 


Required Boundary 


ALIGNED UNALIGNED2 


Minimum 
Storage 


bits 
bits 


bytes 
bits 
bits 


bytes 


bits 
bytes 
bits 


bytes 


(m1) bytes 
(m1+4) bytes 


(m1) bits 
(m1+36) bits 


(n) bytes 


1 word 
1 word 
1 word 
56 OPES 
36 bits 


1 word 


lApplies to both major and member scalar variables. 


2Applies to member scalars only. 
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As the basis for. an example of the layout of a scalar variable, consider 
the following declaration: , 


DCL O01. Al, 


02 PHI FIXED, 


According to the default rules, this declaration is equivalent to: 


DCL O01 Al UNALIGNED, 


02 PHI FIXED BIN(17) ALIGNED, 


Suppose the starting address for PHI is bit 27 of word 103. Then the rules just 
given prescribe the following layout for PHI: 


103 


0 g 18 27 
eee aie re 
PH | supp 1 


This layout is determined as follows: 


104 


1 The layout begins at bit 27 of word 103. 


Zi According to Table 11-1, the required boundary for the variable is 
word, Since the starting address is not at a word boundary, the 
layout begins with one byte of filler storage (fully shaded). 


ae The layout continues with the minimum storage for the variable, 18 
oe aoe 
be Since the required boundary is word, the layout concludes with 18 bits 


of supplementary storage (half shaded). 


The storage available for PHI is a full word, the minimum plus the supplement. 
Therefore, the value of PHI can be stored in a way that is suitable for the 
full-word operations of the hardware. PHI is right-justified in the word to 


eliminate the need for masking and shifting operations. 
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Storage Layout for Member Structures 


To determine the storage layout for a given member structure variable at a 
given word and bit address, proceed as follows: 


1. 


2. 


Begin the layout at the given address. 


Determine the required boundary type for the structure as follows: 


a. Make a list of the required boundaries for the members of the 
structure. 


b. If the structure itself is ALIGNED, then add the boundary word to 
the list. 


og Find the boundary on the list that refers to the largest unit of 
storage and take that to be the required boundary for the 
structure, 


If the starting address is not a boundary of the required type, then 
lay out filler storage up to the next boundary of storage. 


Continue the layout of the structure by laying out storage for each of 
its members. 


If the required boundary is even word or word and the layout does not 
end at a word boundary, then lay out supplementary storage to the next 
word boundary. 


As the basis for an example of the layout of a structure variable, consider 
the following declaration: 


Z.° “Sly 
03. ALPHA DEC(6,2), 
OS BETA. BiTti23, 
03 GAMMA CHAR(4), 


According to the default rules, this declaration is equivalent to: 


DCL 01 UNAL, 


i Si) NAL, 
03 ALPHA REAL FIXED DECIMAL(6,2) ALIGNED, 
03 BETA BIT (12) NONVARYING UNAL, 
03 GAMMA CHARACTER(4) NONVARYING UNAL, 
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Suppose the starting address for the structure Sl is word 72, bit 27. Then the 
rules prescribe the following layout for Sl: 


0 9 18 27 » 
i ER 
ALPHA 
7h SETTTLTT 
75 LET! 
ae i eee 
76 ee er 
GAMMA (cont S1 (suppl 


This layout is determined as follows: 


Ls The layout of Sl begins at bit 27 of word 72. 
fae The list of required boundaries for the members of S1 is: 
word 
bit 
byte 
The maximal boundary from this list is word. Since the layout begins 


on a bit boundary, 9 bits of filler storage are required. Hence, Sl 
begins at word 73, bit 0. 


a5 The layout continues with the 3 members of the structure, Each is 
laid out according to the rules for a scalar, as follows: 


ALPHA The required boundary is word and the minimum storage is 7 


bytes. The layout ends with 1 byte of supplementary WD 
storage. 
BETA The required boundary is bit and the minimum storage is 12 


bits. No filler or supplementary storage is used, 


GAMMA The required boundary is byte and the minimum storage is 4 
bytes. The layout begins with 6 bits of filler storage. No | 
supplementary storage is required at the end. 


4, Since the layout of the last member ends in the middle of a word and 
the required boundary for the structure is word, the layout of the 
structure ends with 2 bytes of supplementary storage. 


The order in which the members of a structure are arranged can have a 
significant effect on the amount of storage required for the layout of a 
structure. As an example, consider: 


DCL O14, 
G28 ELT; 
G2 CELL, 
03 IDENT CHAR(2), 
03 LINK PTR, 
U2 Kk -BiTs 
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The layout for A requires 4 full words, as follows: 


0 9 L8 cf 
60 f PRE GCE SI ERE REST ELSE ER CELE REE ©: 
61 Doan ee LELELELITLLE LEGS. 
IDENT 
: 
63 


ee 


suppleme 


This layout arises from the fact that LINK is an ALIGNED POINTER and specifies a 
word boundary not only for its own storage, but also for the structure A.CELL of 
which it is a member. 


Consider the following revision of the declaration of the structure A: 


DCL O1 A, 
CELE 
03 LINK PTR, 
03 IDENT CHAR(2), 
Oe. teil, 
OZ AW oT Es 


In most cases, this change in the ordering of the members of A has no effect on 
the usage of the structure, but the resulting layout occupies 3 words instead of 
4s: 


60 


61 


EPTTIPLIATLIL ELTA FTL E LACE TA ELT TF 


supplementar 


62 


li 


Some storage is still wasted In this layout.. IDENT, 1, and X could ai] fit in 2 
word, However, to further improve the allocation in storage, a change in the 
level structure is required; that type of change could well affect the usage of 
the structure. 


Consider a different revision of the declaration of the structure A: 


DCL 01 A UNAL, 
G2 | BIT, 
O2 CELL, 
03 IDENT CHAR(2), 
03 LINK PTR, 
U2 XX BIT? 
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Because of the addition of the attribute UNAL for A, the layout uses 2 words 
instead of 4&: 


9 18 £1 


0 
[ IDENT INK 
LINK (cont X IAC supp] 


For this version, however, the interpretation of the value of the POINTER value 
takes more time than for the ALIGNED value. 


60 


61 


Storage Layout for Member Arrays 
To determine the storage layout for a given array variable at a given 
address, proceed as follows: 
ds Begin the layout at the given address, 
jae The required boundary for the array is the same as for the elements of 
the array. if the starting address is not a boundary of the required 
type, then lay out filler storage up to the next boundary of the 


required type. 


oe Continue the layout of the array by laying out storage for each of its 
elements. 


4. If an element does not end at the required boundary, then lay out 


supplementary storage to the next boundary of the required type. 


The alignment attribute of an array is especially important, since it is in 
the layout of large arrays that the alignment can have a significant effect on 
storage requirements. As ag simple ifilustration, consider the following 
declarations: 


DCL. (PM1C50,50) BIT: 


DCL PM2(50,50) BIT ALIGNED; 


The array PM1 requires 70 words, whereas PM2 requires 2500 words, 


For a second example of the layout of an array, consider the following 
declaration: 


2 TABLE(10), 
03 ALPHA FIXED BIN(44), 
03 GAMMA CHAR(1), 
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Then 


The 


According to the default rules, this declaration is equivalent to: 


DOL Us Ss, 


02 TABLE(10) UNAL, 
03 ALPHA FIXED BIN(44) ALIGNED, 
03 GAMMA CHAR(1) UNAL, 


Suppose the starting address for the layout of TABLE is word 51, bit 
the rules prescribe the following layout for TABLE: 


0 g 20 27 
51 pee ee 
En RT 
ALPHA 
55 ALPHA FESPA LID LI CIMA EL Ta} 
ALPHA (suppl TABLE(1) 
Sh a 
GAMMA TABLE (suppl 
DS ATF IL EESTI PEPTIC ET EIA TTT EL TIT 
TABLI SuUDD 1. cont 
_ a ee 
ALPHA 
89 ALPHA PIPES A LAL I SAI IPI EL PEGI ET EL 
cont ALPHA (suppl FABLECIOS 
90 PIL LALETAL EPI TIA SITET TT 
TABLE (suppl 
91 


APETS EC CELS ESE EME SPLICE See eee eee 
ai 


ABLE (supp! ont 


layout is determined, as follows: 


i Tne layout of TABLE begins at bit 20 of word 51, 


2% The list of required boundaries from Table 11-1 for members’ of 


element of TABLE is: 


even word (ALPHA) 
byte (GAMMA ) 


Pll 


an 


The maximal boundary is even word, which becomes the required boundary 
for a TABLE element (and for TABLE itself). Since the layout starts 


on a bit boundary, 16 bits of filler storage are required, Thus, 
First element of TABLE actually begins at word 52, bit 0. 


Lieit 


the 
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aes The layout for each element of TABLE is determined as follows’ (from 
the rules for laying out member scalars): 


ALPHA The required boundary is even word and the minimum storage ( 
is 4S bits. Twenty-seven bits of supplementary storage are ~~ 
required to bring the layout up to the next even word 
boundary. Note that in the resulting double-word the value 
of ALPHA will be right-justified because it is binary. 


GAMMA The required boundary is byte and the minimum storage is one 
byte. No filler or supplementary storage is required. 


ie Since the last member (GAMMA) of the element does not end on the 
required even-word boundary for the element, lay out supplementary 
storage of seven bytes. 


Note that the storage requirements for TABLE can be considerably reduced by 
altering its declaration: 


DCL O15, 


02 TABLE(10) UNAL, 
03 ALPHA FIXED BIN(44), 
03 GAMMA CHAR(1), 


In this case, TABLE will actually begin at bit 27 of word 51, each element = 
will occupy only 6 bytes of storage, and TABLE will end on bit 26 of word 66. 


Lb=1i2 DEO4 


SECTION XII 


INCLUDE FILES 


This section describes the creation and maintenance of the INCLUDE file. 
The INCLUDE file contains the macro bodies that can be referenced in PL/I 
programs by the use of the %INCLUDE statement. The use of the utility program 
SRCLIB is described and illustrated. 


SRCLIB PROGRAM 


The system utility program, SRCLIB, is used to create and maintain an 
INCLUDE file. The actions to be performed are specified by a series of control 
cards. The SRCLIB control cards provide for the initialization and creation of 
the INCLUDE file, subsequent modification by the inclusion and deletion of macro 
text, and copying and listing activities. 


USE OF THE SRCLIB PROGRAM 
The SRCLIB program is called, using a $ PROGRAM control card, from the same 
library file as the compiler. 


$ PROGRAM SRCLIB 


Files Used by the SRCLIB Program 

Several files are used by the SRCLIB program. For each file code, a 
description is given in the following list: 

File Code Description 


-'k INCLUDE file, which contains the macro text to be created or 
maintained. 


IN input file, which contains the control cards and text used by 
the SRCLIB program. 


any input or output file, which can be used either to contribute 
text to the INCLUDE file or save text from the INCLUDE file. 


WK work file, which is required for the activity when the MODIFY 
control card is present. 
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The SRCLIB program gets its directions from the input file, IN. The control 
cards in that file determine the actions to be taken on the INCLUDE file, .L. 
Some of these control cards specify the file code of another file for input to 
or output from the INCLUDE file. The presence of the MODIFY control card makes 
it necessary to include a work file, WK. 


SRCLIB CONTROL CARDS 


SRCLIB control cards give information to the SRCLIB program about the 
creation and maintenance of the INCLUDE file. SRCLIB control cards’ are 
summarized in Table 12-1. Following the table, each control card is described 
in detail. 


Table 12-1. SRCLIB Control Cards 


ALTER Add text to or delete text line-n[, 1line-m] 
from the INCLUDE file. 


COPY Copy specified macro to the text-name, fi le-code[ , BCD] 
specified file. 


CREATE Place new text in the INCLUDE text-name|,file-code| 
file. 


DELETE Delete the specified macro text-name 
from the INCLUDE file. 


INITIAL Initialize the INCLUDE file. 


Lier List the specified macro or the [text-name] 
entire INCLUDE file. 


MODIFY Modify the specified macro in text-~name 
the INCLUDE file. 


SAVE Copy the entire INCLUDE file to | file-code[,BcpD] 
the specified file. 


The text-name is the name of a macro in the INCLUDE file. In all cases, 
the text-name is limited to a maximum of 32 characters, 


The file-code is the two character name used to identify a file. 
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LITER Control. Card 


The * ALTER control card is used to modify the INCLUDE file. A * ALTER 
control card gives the line numbers that are to be modified within the macro 
text. The * MODIFY control card gives the name of the macro to be modified and 
therefore, must always precede a series of ALTER cards. The format of the 
* ALTER control card is as follows: 


1 8 16 


* ALTER line-n[ , 1ine-m] 


where: line-n is a decimal integer 
line-m is a decimal integer 


If only line-n is specified, the text following the * ALTER card is 
inserted in the macro named by the MODIFY control card before the line 
specified. 


If both line-n and line-m are specified, line-n through line-m of the macro 
specified by the * MODIFY card are deleted. If text follows the * ALTER’~ card, 
it is inserted at the point of deletion. 


For example, consider the following sequence of control cards: 


* MODIFY MAC1 

* ALTER 10 
DCL AL. PARED? 
DEL XZ IPLOATS 


* ALTER 20, 24 
* ALTER $15 90 
CALL. Pi; 


The declarations of Xl and X2 are inserted in the macro MACI1 before line 10; 
lines 20 through 24 of MACI1 are deleted; and lines 31 through 36 of MACI1 are 
replaced by the procedure call to Pl. 


COPY Contro]. Card 


The * COPY control card is used to copy a macro from the INCLUDE file to 
the file specified by the file code. The format of the * COPY control card is 
as follows: 


1 8 16 
* COPY text-name, fi le-code[, BCD] 
where: text-name identifies the macro to be copied. 
file-code identifies the file to which to copy the text. 
BCD indicates that the text is to be represented in BCD 
rather than ASCII on the designated file. 
The * COPY control card allows the user to select and copy a single macro from 


the INCLUDE file. To copy the entire INCLUDE file, the * SAVE control card is 
used. 
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CREATE Control Card 


The »* CREATE control card is used to create or extend the INCLUDE file. 
The format of the * CREATE control card is as follows: 


1 8 16 


* CREATE text-name|,file-code| 


where: text-name identifies the name to be associated with the macro 
text. 
file-code identifies the file containing the macro text. 


If the file-code is not specified, the card images following the control 
card in the IN file are used as the macro text. If the file-code is specified, 
the macro text is taken from the file identified by that file code. 


If the text-name specified for the new macro already exists in the INCLUDE 
file or if there is not sufficient space in the INCLUDE file to enter the new 
text, the * CREATE control card is ignored and a warning message printed. 


DELETE Control] Card 


The * DELETE control card is used to delete a macro from the INCLUDE file. 
The format of the * DELETE card is as follows; 


ee ee ea a Nee eee er ee 
* DELETE text-name 
where: text-name indicates the name of the macro to be deleted from. the 


INCLUDE file. 


If the specified macro is not found in the INCLUDE file, the * DELETE card 
is ignored and a warning message printed. 


INITIAL Control Card 


The * INITIAL control card is used to initialize the INCLUDE file. The 
format of the * INITIAL card is as follows: 

1 8 16 

* INITIAL 


An initialized INCLUDE file contains no macro names or text. 
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LiSt Control .Card 


The * LIST control card is used to output the text associated with a macro 
name. Tne format of the * LIST card is as follows: 


i 8 16 


* RES) [ text-name] 
where: text-name indicates the macro whose text is to be output. 


If the text-name is omitted from the * LIST card, the text for all names 
registered in the INCLUDE file is listed. 


MODIFY Control Card 


The * MODIFY control card is used to indicate the macro that Is to be 
modified by the * ALTER cards that follow. The format of the * MODIFY control 
card is as follows: 

z 8 16 

* MODIFY text-name 

where: text-name indicates the macro to be modified by the * ALTER cards. 
If the text-name given on the * MODIFY card cannot be found in the INCLUDE file, 


the * MODIFY card is ignored and a warning message printed, 


The work file, WK, must be furnished when modifying the INCLUDE file. 


AVE Control Card 


The * SAVE control card is used to copy the entire INCLUDE file to the file 
specified by the file-code, The format of the «* SAVE control card is as 
follows: 


1 8 16 
* SAVE file-code [, BCD] 


The file is organized in the system standard format, and unless BCD is specified 
as a parameter, the file is represented in the ASCII character set. 
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An INCLUDE file is saved as a series of control cards and macro text, as 
follows: 


1 8 16 

* INITIAL 

* CREATE text-name-1l 
text-1l 

* CREATE text-name-2 
text-2 

* CREATE text-name-3 
text-3 


An INCLUDE file that has been saved, therefore, can be used as the file 
identified by the file code IN to produce an INCLUDE file. 


EXAMPLES 


Examples that illustrate the creation and maintenance of an INCLUDE file 
are included in this section. The first example illustrates the creation of the 
INCLUDE file. In the next example, the text of several macros is modified. 
Next, the INCLUDE file is saved, several more changes are made, and the file is 
saved again. The first INCLUDE file that was saved first is then used in a PL/I 
program, 


Example 1 - Creation of an INCLUDE File 


In this example, the INCLUDE file is initialized, and then three macros are 
added. 


Die eget een 
$ PROGRAM SRCLIB 

$ PRMFL .L,W,R,MY/INCL 

$ DATA IN 

* INITIAL 

* CREATE TEXTS 


DEL. Xt FEXED: 
DCL. .DE. Fi XED (DECIMAL: 
DEL -BL BITCh?y: 
* CREATE TEXTZ 
Pl: PROCI1; 
DEL A. FEAEBS 
DCL -& “FF LAED: 
A=B*SQRT(B); 
END; 
* CREATE. TEATS 
DCL El ENTRYCFIXED); 
DCL E2 ENTRYCFIXED,FIXED); 
$ ENDJOB 
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mple 2 - Modifi 


In this 
statement is 
have been 
of the 


ation of an_IN D 


example, 
inserted 
changed are 
INCLUDE file, 


Fil 


line 2 of the macro TEXT1 is replaced and a %INCLUDE 
in the macro TEXT2 before line 3. Then the macros’ that 
listed, Note that, since this job involves modification 
the work file, WK, must be included in the job, 


16 


$ PROGRAM SRCLIB 
$ PRMFL .L,W,R,MY/INCL 
$ FILE WK,A1R,10L 
$ DATA IN 
" MODIFY TEXT1 
. ALTER 2,2 
DCL Cl CHAR(3); 
x MODIFY TEXT2 
. ALTER 3 
INCLUDE TEXT3; 
. LIST TEXT1 
. LPST TEXT2 
$ ENDJOB 


Example 3 - Saving the INCLUDE File 


In this example, 


by the file code 


identified 
in the file, 


is saved as the file 
changes are made 


INCLUDE file MY-INCI1 
several experimental 


the 
KY: 


including the deletion of a macro; and the new INCLUDE file MY-INC2 is saved as 


the file identified by the file code YZ. 
1 8 16 
$ PROGRAM SRCLIB 
$ PRMFL stow RpMY 71 NEL 
$ FILE WK,A3R,10L 
$ TAPE XY,A1D,,99999,,MY-INC1 
$ TAPE YZ,A2D,,99999, ,MY-INC2 
$ DATA IN 
* SAVE X¥,6CD 
* Bees 
* MODIFY TEXTI1 
* ALTER ioc 
* DELETE: TEXTS 
* SAVE ¥Z;6CD 
* LIST 
$ ENDJOB 
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Example 4 - Use of a Saved INCLUDE File 


In this example, the INCLUDE file saved in the previous run is re-instated 


and a program referencing the INCLUDE file given. X | 
1 8 16 
$ PROGRAM SRCLIB 
$ PRMFL ~L,W,R,MY/ INCL 
$ TAPE IN, A1D,,99999,,MY-INC1 
$ PL1 Lis 
$ PRMFL ~L,R,R,MY/ INCL 


P: PROC OPTIONS(MAIN); 
ZIUNCLUBDE- TEXTS 
AL = 33 
OY 3 
SENCLUDE TEATZ: 
X1=2; 
END; 
$ ENDJOB 
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SECTION XIII 


DEBUGGING PL/I PROGRAMS 


When the execution of a PL/I program terminates abnormally, the execution 
report produced can be used to obtain useful information about the state of the 
program upon termination. This section gives general rules for interpreting § an 
execution report and then illustrates the use of some of these rules with an 
example of a program that terminated on the occurrence of the ZERODIVIDE 
condition. 


MEMORY LAYOUT 


The memory layout during the execution of a PL/I program is given here. 
Later in this section, the actual memory layout for an example is diagrammed. 


Slave Prefix 
102 


PL/I External Procedures 


PL/I External Static Storage 


PL/1 Bulltin Functions; 
Operators, and Routines 


PL/I Automatic Storage 
(Stack Space) 


System Storage 


Load Limit 


If the low end of system storage nears the stack frames, then additional 
memory for system storage is requested from the operating system. When the 
stack frame space is exhausted or system storage cannot be obtained, the 
activity is terminated with abort code PC. 
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ABNORMAL TERMINATION 


When a program terminates abnormally, the reason for the termination is 
indicated either by an abort code or by a message from a default ON unit. 
Following this identification, an error trace-back is given, which indicates the 
procedures that were active at the time the termination occurred. Following the 
error trace-back, a memory dump is listed if the DUMP option is specified on the 
= EXECUTE -control card. 


Abort Codes 


If the compilation or execution of a PL/I program terminates abnormally for 
reasons not handled as conditions, an abort code is listed. Table 13-1 lists 
the abort codes and gives, for each code, its meaning and the time at which it 
can -occur’ lf the code can occur during compilation, an X appears in that 
column; if during execution, an X appears in the execution column. 


Table 13-1. PL/I Abort Codes 


| OCCURS DURING 


Code Meaning Compilation |Execution 


Argument and parameter do not match. | X 


Core resource exhausted. Try extending X X 
the core limit. | | 


ERROR condition has occurred and user X 
did not supply ON-unit for the condition. 


Fatal source program error. X 
Compiler interface detected an unrecoverable X 


error. The system prints a brief comment on 
the file P*. 


lllegal control card on the file A*. X 
lllegal $ ALTER card on the file A*. X 
l!l1legal media code on the file A*. X 
lllegal media code on the file S*. X 
lllegal binary card, other than type 5, X 
on the file S*. 

Invalid sequence number on the file S*. X 
!1legal COMDK format on the file S*. X 
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ON Units 


Many exceptional conditions can be detected during the execution of a PL/I 
program. The detection of an enabled condition causes the established ON unit 
for that condition to be executed. If the user supplies an ON unit for the 
handling of the condition when it is’ signalled, that ON unit is executed; 
otherwise, the system ON unit is executed. 


In general the system-supplied ON unit prints an identifying message of the 
form: 
*xe* SIZE CONDITIONCONCODE = 703) OCCURRED. **** 


The message gives the condition name and number. The condition numbers”) are 
assigned according to the following list: 


Condition 


Number Support Routine 
1 = 100 Math library 
101 - 300 Record and stream 1/0 
301 - 600 |[/O run-time support yoy 
601 - 999 PL/| operators 
1000 Signal statement 
1001 - Not assigned 
Appendix | of this manual gives, for each ONCODE number, a more complete 


description of the reasons for its occurrence. Following the printing of the 
message, the system-supplied ON unit signals the ERROR condition, which prints 
the error trace-back and returns to GCOS for the termination of the job. 


Error Trace~Back 


Following the line that identifies the reason for the abnormal termination 
of the execution, an error trace-back is given. The error trace-back lists the 
PROCEDURE blocks that were active at the time the execution terminated, 
including any PROCEDURE or BEGIN blocks internally created by the compiler. The 
PROCEDURE blocks are listed in the order in which they were activated, the first 
being the PROCEDURE with the OPTIONS(MAIN) attribute and the last being the 
system routine that was activated when the execution was terminated. 
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For each block the following information is given: 


ENTRY NAME The name of the procedure or block. 


LINE # lf the procedure was compiled with the SNUMBER- option, the 
line number in the source listing at which the ERROR 
condition was signalled is given. 


STATEMENT # If the procedure was compiled with the SNUMBER- option, the 
statement number within the line is given. 


LOCATION The absolute address in memory of the instruction at which 
either the ERROR condition was signalled or transfer was 
made to the next block listed in the error trace-back. 


OFFSET The address, on the object listing, of LOCATION relative’ to 
the entry point of the activated block. 


STACK The absolute address of the first location of the stack 
frame assigned to the procedure or block. 


The error trace-back is very useful for determining the exact location of 
the error that terminated the execution and for providing address information to 
locate PL/I variables. The rules for locating PL/I variables are given in_ the 
following paragraphs. Following these rules, a comprehensive example is given 
that illustrates the use of an error trace-back. 


Lo ing PL/| Variab] in Memor 


Rules for locating the following types of variables in memory are given in 
this section: 


EXTERNAL STATIC variables 
EXTERNAL PROCEDURES 

INTERNAL STATIC variables 
LABELS 

INTERNAL PROCEDURES 
AUTOMATIC variables 

EXTERNAL PROCEDURE arguments 
INTERNAL PROCEDURE arguments 


Locating a memory address requires reference to several sections of the compiler 
output listing. The options given on the $ PL1 control card for the compilation 
determine the sections of the output listing that are printed. A detailed 
description of the sections of the compiler output listing and the associated 
options is given earlier, in the section on the "Compiler". 


After the rules for locating the above items are given, a comprehensive 
example illustrates the location of some PL/I variables in memory by applying 
these rules to the listings produced from its compilation and execution. 
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EXTERNAL STATIC VARIABLES 


To determine the location in memory of an EXTERNAL STATIC variable, proceed 


i 4 as follows: 


ce If the name of the variable exceeds six characters or contains the 
character '$' or '_', obtain the converted name from the Storage Space 
| and External Symbol section of the compiler output listing. If this 


listing is not available, convert the name according to the conversion 
rules given in Appendix F of this manual. 


| 2 Locate the block common with the variable name (or converted variable 
name) on the Loader Map. The location given to the right of the name 
is the loaded location for the EXTERNAL STATIC. variable. This 
location will immediately follow the first external procedure in which 
the variable occurs. 


If the EXTERNAL STATIC variable is a structure, continue as follows to locate 
the members: 


% Obtain the word offset (in octal) and bit offset (in decimal) for the 
structure member from the Symbol Table section of the compiler output 
listing, 


4. Add the word and bit offset to the origin obtained in Step 2 to locate 
the member. 


| EXTERNAL PROCEDURES 


To determine the location in memory of an EXTERNAL PROCEDURE, proceed as 


follows: 
ae If the name of the EXTERNAL PROCEDURE exceeds six characters or 
contains the character '$' or '_', obtain the converted name from the 
Storage Space and External Symbol section of the compiler. output 
listing. If this listing is not available, convert the name according 
to the conversion rules given in Appendix F of this manual. 
2% Locate the name or converted name on the Loader Map. The location 


given at the left margin on the Loader Map is the loaded location for 
the origin of the procedure, including INTERNAL STATIC’ storage. The 
location to the right of the name is the loaded location for the entry 
point to the procedure, 


To determine the location of a statement within an EXTERNAL PROCEDURE, continue 
as follows: 


Ai, Locate the relative location of the statement by consulting the Object 
Map section of the compiler output listing. 


4. Add the relative location for the statement to the procedure origin 
obtained in Step 2. 
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When more than one statement is given on a line in the source program, the 
relative location of the statement can be obtained from the Object’ Program 
section of the compiler output Listing. The Object Program Listing is 
annotated for convenient interpretation. The relative location of the 
instruction is given at the left and the correspondence to the source listing in 
terms of statement and line number is given on the right of the object code 
i ey oe 


INTERNAL STATIC VARIABLES 


To determine the location in memory of an INTERNAL STATIC variable, proceed 
as follows: 


Ls Locate the name of the INTERNAL STATIC variable in the Symbol Table 
section of the compiler output listing to obtain the location of the 
variable relative to the origin of the procedure. 


25 Locate the procedure origin in the Loader Map by following the rules 
given earlier in this section for locating an external procedure. 


ie Add the relative location of the INTERNAL STATIC variable to_ the 
procedure origin to obtain the location in memory of the variable. 


An INTERNAL STATIC variable is assigned a location in memory only if it is 
referenced (either explicitly or because an item based on it is’ referenced). 
Therefore, INTERNAL STATIC variables that are defined but not referenced do not 
have a relative location in the Symbol Table section. 


LABELS 


To determine the location in memory of a LABEL CONSTANT when the Object 
Program section of the compiler output listing is available, proceed as follows: 


Ls Locate the label in the Object Program section of the compiler output 
listing to obtain the location of the label relative to the procedure 
Orban. 

ae Locate the procedure origin in the Loader Map by following the rules 


given earlier in this section for locating an external procedure. 


3. Add the relative location of the label to the procedure origin to 
obtain the location in memory of the instruction so labeled. 


if the Object Program section of the compiler output listing is not 
available, proceed as follows: 


Big Locate the label or label array in the Symbol Table section of _ the 
compiler output listing under the heading "NAMES DECLARED BY EXPLICIT 
CONTEXT'' to obtain the relative location within the procedure. 


Oar Locate the procedure origin from the Loader Map by following the rules 
given earlier in this section for locating an external procedure. 


S lf the label is unsubscripted, add the relative location of the label 


to the procedure origin to obtain the location in memory of the 
instruction so labeled. 
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If the label is subscripted and the lower bound of the label array is 
zero, add the relative location of the label array to the procedure 
origin to obtain the transfer vector, then add the subscript value to 
the origin of the transfer vector to obtain the transfer address for 


the instruction associated with the subscripted label. If the lower 
bound of the label array is other than zero, a further adjustment must 
be made. 


INTERNAL PROCEDURES 
To locate an INTERNAL PROCEDURE, proceed as follows: 


se Locate the relative location of the INTERNAL PROCEDURE in the Symbol 
Table section of the compiler output listing under the heading ''NAMES 
DECLARED BY EXPLICIT CONTEXT". 


i aF Locate the origin of the external procedure in the Loader Map 
following the rules given earlier in this section for locating 
external procedures. 


5% Add the relative location of the internal procedure to the procedure 
origin of the external procedure to obtain the location in memory for 
the internal procedure, 


AUTOMATIC VARIABLES 


To locate the relative location of an AUTOMATIC variable, proceed as 
follows: 


1 ae Locate the relative location of the AUTOMATIC variable in’ the Symbo ] 
Table section of the compiler output listing. 


ja Locate the origin of the stack frame for the current invocation of the 
procedure from the error trace-back. 


be Add the relative location of the AUTOMATIC variable to the stack frame 
origin to obtain the location in memory of the AUTOMATIC variable. 


If the error trace-back is not available, the stack frame for the current 
invocation of the procedure can be obtained by following stack frame linkages. 
The stack frame linkages can be followed either from the first stack frame ina 
forward direction or from the last stack frame in a backward direction. ie is 
procedure has several active invocations, the current active invocation can be 
obtained most efficiently by beginning from the last stack frame and _ working 
backwards. 
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The format of the stack frame is as follows: 


0 
1 
Z 
3 
4 Temporary Storage for 
Operators 
5 
6 
Last word of AUTOMATIC Storage 

where: AP is the location of the calling sequence. 

LP is the lrocatton-of cali -* 1. 

OC is the offset relative to stack frame of the enabled 


condition chain. 
EL is the location of the entry + 1. 


CS is the location of the stack frame header for caller 
(index register SP = 2). 


SF is the location of the stack frame header for the last 
invocation of the enclosing procedure. 


SB is the last location in this stack frame (including 
temporary). 


TO i¢ the -first Ttoecation used for temporary (frame 
extension). 


For a more detailed explanation of the stack frame format, refer to Detailed 
Stack Frame Format, later in this section. 
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To 


a, 


TO 
follows: 


y OE 


The 


follow stack frame linkages in a forward direction, proceed as’ follows: 


Locate the address of the first stack frame from the upper half of 
word 37 in the memory dump. 


Examine the lower half of word 1 (EL) to obtain the locationt+tl of the 
entry point of the associated procedure. Compare this addresstl with 
the address obtained on the Loader Map for the entry to the procedure 
in question. lf the addresses agree, the stack frame for the 
procedure is located. The stack frame for the current invocation of 
the procedure is the last stack frame located for the procedure using 
this method. 


lf the addresses do not agree, pick up the location of the next stack 
frame from the first half of word 3 (SB). If this address is not an 
even address, round up to an even address. 


Return to Step 2. 


follow the stack frame linkages in a backward direction, proceed as 


Locate the address of the last stack frame from index register 2. Bi 
the abnormal termination occurred within a GFRC routine, however, 
index register 2 no longer has the last stack frame and the_- stack 
frame linkages must be followed in a forward direction. 


Compare the addresses as in Step 2 for forward linking. 
If the addresses do not agree, pick up the location of the preceding 


sisck frame from the Tirst: halt of word 2 (Cs). 


address obtained from the stack frame field EL can be used to obtain 


the name of the external procedure from the memory dump. Consider the sequence 
of instructions preceding the procedure entry for a procedure named CALCULATE. 


ASCII CALC 
ASCII ULAT 
ASCII E 


ZERO number of parameters, number of characters in name (= 9) 
TSXO .P0090 (external entry operator) 

ZERO 0, number of words of automatic storage used 
instructions for first executable statement 
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The field EL in the stack frame contains the address etl. Subtracting 2 from 
the address in EL gives the location in which the number of characters in the 
name is stored. The number of characters in the name determines the number of 
words used to store the name, and thus the name of the external procedure can be 
obtained. 


EXTERNAL PROCEDURE ARGUMENTS 


To determine the location in memory of an argument of an EXTERNAL 
PROCEDURE, proceed as follows: 


Ls Locate the relative location of the argument list within the stack 
frame of the calling procedure. This can be done in one of two ways, 
depending on the availability of the object program listing. 


If the Object Program section of the compiler output listing for the 
calling program is’ available, the relative location can be obtained 
from the generated code as follows: 


EAX6 n,sP 
TSXLP procedure 


The number n is the relative location (in decimal) within the stack 
frame of the calling procedure for the argument list for the called 
procedure. Add the relative location to the stack frame origin of the 
calling procedure. 


If the Object Program listing is not’ available, information can be 
obtained from a memory dump. The upper half of word 0 of the stack 
frame of the called procedure gives the location of the argument list 
within the stack frame of the calling procedure. 


23 The format of the argument list is described in detail earlier, in the 
Section on "Linking PL/I and Other Languages". Given the origin of 
the argument list, the description of Section on "Linking PL/I and 
Other Languages" gives the information necessary to locate any 
argument within that list. 


The location of an argument of an external procedure is illustrated in the. 
examples that conclude this section. 
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INTERNAL PROCEDURE ARGUMENTS 


To determine the location in memory of an argument of an INTERNAL 
PROCEDURE, consult the Storage and External Symbol section of the compiler 
output listing to see whether or not the INTERNAL PROCEDURE shares the stack 
frame of the enclosing procedure. Then proceed as follows: 


abe If a stack frame is created when the internal procedure is called, 
then the rules for locating an argument are identical to the rules for 
locating an argument of an external procedure. 


age However, if the stack frame is shared, the location within the stack 
frame of the calling procedure for the argument list can be obtained 
in one of two ways, depending on the availability of the Object 
Program listing. 


If the Object Program section of the compiler output listing for the 
calling procedure is available, the location can be obtained from the 
first instructions generated for a shared frame internal procedure, 
namely: 


STXAP n,SP 
SXLLP n,SP 


The number n is the relative decimal location in the stack frame of 
the enclosing procedure for the word whose upper half contains the 
loaded location of the argument list of the called procedure. 


If the Object Program Listing is not available for the calling 
procedure, the above instructions can be located by consulting the 
Object Program Map Listing. The source line in the map for the 
internal procedure locates the above instructions. The loaded location 
of these instructions, and hence the value of n, can then be obtained 
from a memory dump. 


Detailed Stack Frame Format 


A detailed diagram of the stack frame format is given in Figure 13-1. The 
relationship of the stack frame to the argument list, calling sequence, and 
enabled condition names is also illustrated in this figure. 
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The PL/I condition signalling mechanism makes use of several external 
variables which may be of interest. Their converted names and uses are listed 
in Table 13-2. Their location in memory may be determined from the load map 
where their Block Common items usually first appear in relation to module ZLKV. 
These Block Commons will contain values related to the most recently signalled 
condition to which each is pertinent. 


Table 13-2. Frequently-Used Block Common Items 


OCODE FIXED BINARY the oncode. 


QQNDEX FIXED BINARY index in 60URCE of the offending 
character. 


6OURCE CHARACTER( 256) bad string causing conversion 
VARYING error. 


LOFILE CHARACTER( 32) file name for which the CONVERSION, 
VARYING NAME, ENDFILE, TRANSMIT, RECORD, 
KEY, or UNDEFINEDFILE condition has 
been signalled. 


30NLOC CHARACTER( 256) a character string containing the 
VARYING name of the faulting procedure. 


7OIELD CHARACTER( 256) the bad identifier in the GET DATA 
VARYING statement. 


Z30NKEY CHARACTER( 256) the character string containing the 
VARYING key of the record for which the 
ENDFILE, TRANSMIT, or ONKEY condition 
has been signalled. 


EXAMPLE 


The following example is intended to illustrate the output resulting from 
an abnormal termination of a PL/|I program. The computations being performed in 
the program are of no interest, except that the third execution of P2A is 
intended to abort the third time through to provide the execution report. 
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The job consists of the compilation of four separate external procedures 
and the execution of the results of the compilations. Figure 13-2 gives the 
control cards and input cards for this job. 


il 8 16 
$ SNUMB JOBI14 
$ IDENT 
$ OPTION Pld 
$ Pia LIST,SNUMBER 
c. PROC OPTIONS(MAIN) ; 


DEL. Pl. ENTRYCE AED)? 
DCL P2 ENT RISE ICED FIXED): 
DOLL Alg Aes ROD PL AEDS 
DO. AL = 2 BE 2b Tes 8; 
RT i I ae as 
CALL -PICK2) 3 
END; 
DO °XS = 2 BY 2. TO: O03 
Ke 2 RS: = BY 
CALL P2(X2,X3); /* ABORTS THIRD TIME THROUGH «/ 


END; 
END; 
$ PL1 LIST 
Pl: PROC(A); 


DCL (A,X) FIXED; 
Xk = SQRT(A); 
PUT LIST(X4,A); 


PUT SKIP: 
END; 
$ PL1 LIST,SNUMBER 
P23 PROC(A,B); 


DCL (A; BeXkS) -PUXERs 
DCL P2A ENTRYCFLXED,FIXED)> 


X5 = A**2; 
CALL P2ZACX5,B); 
END; 
$ PLI LIST,SNUMBER 


P2A: PROC(CA,B); 
DGh. AA, By, AG) FEREOS 
X6 = (B * 128) / A; /* ABORTS ON ZERODIVIDE */ 
PUT LISTCA, By-AG 23 


PUT SA LPs 
END; 
$ EXECUTE) DUMP 
$ LIMITS 10, 40K,-2K 
$ ENDJOB 
*k*k*XEOF 


Figure 13-2. Deck Setup for Example 
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For each external procedure, the option LIST is specified on the ¢$ PL1 
control card. Therefore, the compiler output listing for each procedure 
contains the following sections: 


Option listing 

Source Program listing 

Symbol Table listing 

Storage and External Symbol listing 
Object Program Map listing 

Object Program listing 


Figure 13-3 contains the compiler output listing, composed of these _ sections, 
for the external procedure P2A. Each of the other external procedures produces 
the same logical sections of the compiler output listing. The listing, as it 
appears in Figure 13-3, is somewhat compressed, but all the information is 
retained. This listing is used later in the section to locate some variables in 
memory. 
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Figure 13-4 contains the relevant portion of the Loader Map. This’ listing 
is used later in the section to obtain the loaded locations for the origin and 
entry points of the external procedures. 
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Figure 13-5 contains the execution report produced upon the abnormal 
termination of the program. As planned, the termination occurred on the third 
execution of the external procedure P2A. 


First, the system ON unit for ZERODIVIDE prints an identifying message, 
then signals the ERROR condition. The system ON unit for ERROR prints the error 
trace-back and returns control to GCOS. Since the DUMP option is given on the 
$ EXECUTE control card for the run, a memory dump is produced. The memory dump 
in Figure 13-4 has been edited for inclusion in this manual so that only the 
relevant portions appear. 


Following the memory dump, the information output by the program on 
SYSPRINT is listed (see last page of Figure 13-5). 
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Gross Memory Layout for the Example 


The Loader Map, given in Figure 13-3, lists the loaded locations of the 
user-defined external procedures and support system routines. From this 
information, the gross memory layout for the job can be diagrammed, as _ follows: 


Slave Prefix 
External Procedure P 


External 


Le5 -Entry Point to P 


Procedure Pl 2uh Entry Point to Pl 


Procedure P2 


External Procedure P2A 


PL/I Builtin Functions, 
Operators, and Routines 


External 


G56. Entry Pornt. to-P2 


Sh. Entry PoInt. to. PZAa 


53120 


PL/I Automatic Storage 


System Storage 


Error Trace-~Back for the Example 


The error trace-back for this example (Figure 13-4) indicates that the 
external procedures P, P2, and P2A were active at the time the ZERODIVIDE 
condition was signalled. The system routine PLI_SIGNAL_, the last routine 
executed, handled the condition. 


Since the external procedures P, P2, and P2A were compiled with the SNUMBER 
option, the line and statement number currently being executed are given in the 
error trace-back. Line 11 in the external procedure P is the call to P2; line 5 
in the external procedure P2 is the call to P2A; and line 3 in the external 
procedure P2A, as can be seen in the Source Program section of the compiler 
output listing in Figure 13-3, is the calculation that caused the ZERODIVIDE 
condition to be signalled. 


Locating an AUTOMATIC Variabl] 


Consider the location of the variable X6 in the external procedure P2A. X6 ; 
is an AUTOMATIC variable, so the rules for locating an AUTOMATIC variable are ‘ ) 
applied, as follows: 


i lee The relative location of the variable X6 in the Symbol Table listing 
of Figure 13-3 is 000006. 


ae The origin of the stack frame for the current invocation of P2A_ from 
the error trace-back is 053154. 


>. The location of the AUTOMATIC variable X6 in memory is then: 


053154 
+ 000006 
053162 


Examination of the dump of Figure 13-5 indicates that location 053162 contains 
the value 000000000001. Note that this value is meaningless because X6 was’ not 
evaluated (and stored) when the ZERODIVIDE condition was signalled. Since X6 is 
an AUTOMATIC variable, its space may be otherwise used between calls to P2A. 
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Current Stack Frames for the Example 


If the error trace-back for this example were not available, the stack 
frame for an external procedure could be located by either of the methods 
described earlier in this section. If the forward method is applied, the 
location of the first stack frame is obtained from the upper half of word 37 and 
the results of following the links can be diagrammed, as follows: 


Stack Frame for P 


Stack Frame for P2 


Stack Frame for P2A 
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Note that the lower half of word 1 contains the entry+1l to the associated 
procedure. Consider the stack frame for P2A. The lower half of word 1 contains 
562. The entry to P2A can be obtained from the Loader Map and is found to be 
561. Therefore, in the absence of other information, the procedure associated 
with the stack frame can be determined in this way. ‘ ] 


Locating an Argument List 


Consider the location of the argument list for the external procedure P2A. 
The rules for locating an external procedure argument are applied, as _ follows: 


Ls Suppose that the Object Program Listing for the calling procedure, P2, 
is not available. 


The upper half of word 0 of the stack frame for P2A gives the loaded 
location (053150) within the stack frame of P2 for the argument list. 


24 The argument list from the memory dump is: 
000000000002 - indicating two arguments 
053146000000 - location of first argument (A) 
053130000000 - location of second argument (B) 


From the memory dump the value of the arguments are, as follows: 


053146 000000000000 (A) 
053130 000000000006 (B) 


Although the parameters are declared to be 17 bits in length, the default 
alignment assumption of ALIGNED causes them to be represented for ease of access 
iftca. Tul? word. 
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SECTION XIV 


EFFICIENCY CONSIDERATIONS 


Several measures of efficiency can be applied to a computer’ program. The 
program can be efficient in terms of execution time, storage space, or clarity 
of expression. Sometimes these different measures of efficiency are compatible; 
sometimes, however, one measure of efficiency must be sacrificed to increase 
another. 


The rules for clarity of expression apply in a general way to all 
programming languages and do not change from one implementation of PL/I to 
another, Therefore, rules for clarity of expression are not discussed here. On 
the other hand, the rules for obtaining efficiency of time and storage are 


closely related to the design of the host computer and the way the language is 
implemented, Therefore, these efficiency rules are discussed in this section. 
First, some general rules are given for the efficient use of PL/I. Then 


rules are given that increase one measure of efficiency at the expense of the 
other measure. 


GENERAL RULES FOR IMPROVING EFFICIENCY 


The rules given in this section can be applied to improve the general 
efficiency of a PL/I program. 


Data Types 


The data type should be chosen to suit the type of operation. In general, 
the following rules apply: 


& Integer values (such as subscripts, counters, and indexes) should be 
declared FIXED BINARY. 


a Noninteger values should be declared FLOAT BINARY, except in the case 
where exceptional precision is required; for exceptional precision, 
FLOAT DECIMAL should be used, (However, be aware of potential 
incompatibility with a future PL/I system. See Section X at the end 
of the paragraphs on DATA.) 


i A numeric picture variable should not be used in a complicated 
arithmetic calculation. Picture variables are intended for use in 
situations in which input-output is important and calculations are 
simple, 
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A detailed set of guidelines for the choice of data types can be found in the 
PL/| Reference Manual. 


Data Conversions 


Data conversions are time-consuming and should be avoided whenever 
possible. Some hints for avoiding data conversions follow: 


@ Avoid unnecessary conversions by carefully matching the data types of 
variables. Fven a difference in the number-of-digits or scale-factor 
in the precision attribute can cause a conversion to occur. 


s Avoid unnecessary assignment to a target that requires promotion of 
the aggregate type on the right-hand side. 


® Avoid unnecessary conversion of arguments in a procedure call or 
function reference by using by-reference arguments’ rather than 
by-value arguments. In order for an argument to be handled 


by-reference every detail of the storage type of the argument must 
match the storage type of the corresponding parameter. 


@ Avoid excessive conversion of pictured values to arithmetic values. 
As noted in the above paragraph on "Data Types" picture variables are 
intended for use in situations where input-output is important = and 
calculations are simple. 


Varying Strings 


The handling of NONVARYING strings is more efficient than the handling of 
VARYING strings. The use of VARYING strings increases both the amount of 
storage that must be allocated for the string and the amount of object code that 
must be generated to handle the string. 


| Debugging Constructs 


Constructs used for debugging should be removed before the program enters 
production. These constructs include: 


& Data-directed stream input-output statements. 
€ The SNUMBER option, used for error trace-back information. 
© Condition prefixes for the SIZE, SUBSCRIPTRANGE, STRINGRANGE, and 


STRINGSIZE conditions. 


All of these features are costly in terms of execution time and storage use, 


RULES FOR IMPROVING TIME EFFI z 


The rules in this section are useful for improving the time efficiency of a 
PL/| program. Some of these rules improve the execution time of a program at 
the expense of storage; others, at the expense of program clarity. 
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Alignment of Structures 


Variables with the ALIGNED attribute are stored for efficiency of access. 
Therefore, if a frequently-accessed variable is normally assigned the default 
attribute UNALIGNED, the variable should be declared ALIGNED. UNALIGNED is’ the 
normal default alignment for nonvarying strings and structures. More efficient 
code can be generated if level 01 structures are declared ALIGNED. 


If a frequently-accessed variable must be declared UNALIGNED, then’ the 
value of the variable can be moved to an ALIGNED temporary for access. Consider 
the variable X in the structure TABLE: 


DEL QL TABLE, 
UZ 4% FLXED ONAL, 
O2 Cl. CHARCG), 
02 C2 CHAR(8); 


The structure TABLE occupies four words. The access of X is accomplished by 
assigning X to the ALIGNED temporary TEMP, as follows: 


DCL TEMP FIXED; 
TEMP=X; 


Y=TEMP; 


Z=TEMP; 


The subsequent accesses of TEMP are more efficient than accesses of X. However, 
if the value of TEMP is changed, it must be assigned to X before any access of 
the variable TABLE. 


Blocks and ON Units 


BEGIN blocks and ON units involve considerable overhead at activation and 
termination. Extensive use of such block structure in a program should be 
avoided if time efficiency is the principal consideration. Internal PROCEDURE 
blocks, however, are reasonably efficient provided they are not used 
recursively. 
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String Assignment 


The use of the STRING built-in function to assign string constants to a 
contiguously stored series of bit strings is more efficient than assignment on 
an element-by-element basis. Consider the following structure: 


DCL 01 STR ALIGNED, 
02 AF URED, 
Oz By 
03 Bl BITC1) UNAL, 
03 62 BITCT): UNAL 
05° BS BITC2Z) UNAL: 


The following assignment statement 
STRING(B)='0101'B; 


is equivalent to and more efficient than the element-by-element assignment: 


The declaration of a constant with a descriptive name, in this case, is 
sometimes clearer: 


DCL CLEAR_MASK BIT (4) INIT (''0101"B); 


STRING (B) = CLEAR_MASK; 


Fixed-Point Multiplication and Division 


The use of the MULTIPLY and DIVIDE built-in functions sometimes reduces the 
number of instructions required for the evaluation of an expression. In 
particular, the use of the built-in functions is efficient when the operands are 
single precision FIXED BINARY variables and the result of the operation is. also 
a single precision FIXED BINARY variable. Consider the following statements: 


DCL Liga, KM). F LXER: Bi NARYCIS)3 


sa 
nou 


ae ee ae 
eho es 


The following use of the built-in functions is more efficient for this case: 


DYVIDECT 2,18, 0) + Ks 
MOLT EPA Cake S078): +s 


= 
nou 
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Fixed-Point Addition and Subtraction 


The precision of intermediate results of arithmetic operations can have an 
adverse effect upon efficiency. Consider the following example: 


DCL, tigdsh? FPXEDCS5) s 


According to the rules of PL/I, the number-of-digits of the intermediate result 
of the addition or subtraction operation is one more than the maximum 
number-of-digits of the operands. In this example, the number-of-digits of the 
intermediate result requires a double precision number. Therefore, object code 
is required to convert from single to double precision for the intermediate 
result and from double to single precision for the assignment to K. 


Suppose I, J, and K are declared in the following way: 


DCL £450, 8) FIXER CIO) 3 


Here, the intermediate result is a single precision number and no conversion is 
necessary. 


Scale-Factor Conversion 


Scale-factor conversion can be avoided in the addition and subtraction of 
decimal fixed-point numbers by declaring the same scale-factor for each 
variable. For example, consider the following addition: 


DCE. K FIAED: BECCS, 2) 
DCL Y¥ FIAED DECCO,1)> 
DCE: 2-FU AED DECC, 52% 


Lee ORS 


The following version of these statements is more efficient: 


DCL A FINED DECUG, 37+ 
DCE BIAED DEC CS. 3) 
DCL. “2 PASED BEC T5303 
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dress Calculation 


lf a reference with multiple locator-qualifiers is used frequently, the _ 
introduction of temporary storage increases the efficiency of the program by ’ 
eliminating the need for repeated complex address calculations. Ww 


Assume that BASE1 and BASE2 are based variables and Pl, Ql, and Rl are 
pointers, and consider the following program fragment: 


RI=>BASEL.R2Z->BASEZ.X PI=> BASEL. P22 BASEZ. x 
Qi->BASEL. Q2=>5ASEZ. X3 
Pl= BASEL. P2=>BASEZ. Y 


Q1->BASE1.Q2->BASE2Z.Y; 


RI SAS EL. RZ BASEL. Y 


ae | i 


The addressing can be made more efficient, in this case, by the use of the 
pointers, P, Q, and R, as follows: 


PioS Fir cBASe ks 23 
Q = Q1->BASEL.Q2; 
R = R1->BASE1.R2; 
R->BASE2.X P=>BASEZ.<X * Q->8ASEZ.X> 


R-DBASEZ.¥ = P=>BASE2..Y - (Q=oBASEZ. 13 


Another example of the effective use of temporary storage follows. 
Consider, first, the following program fragment: 


IF SUBSTR(S,1,1)="A" ! 
SUBSTR(S,1,1)="8" ! 
SUBSTRCS, Io 178" C" WZ 
THEN GOTO L1; 


ST = SUBSTR(S,I,1) !! "D"; 


If the result of the SUBSTR function is assigned to a temporary, the resulting 
program is more efficient: 


CHARI = SUBSTR(S, 1,1); 
[IF CHAR1="A" ! CHAR1="B' ! CHAR15=''C" 
THEN GOTO LI; 
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Logi Expressions 


The use of general logical expressions involving relational operators 
should be avoided. A series of simple IF statements is more efficient than a 
single IF statement with a multiple condition test. 

For example, the statement 

IF X=Cl 
THEN IF Y=C2 
THEN IF Z=C3 
THEN GOTO EXIT: 
is more efficient than 


[IF X=Cl & Y=C2 & Z=C3 THEN GOTO EXIT; 


Logical expressions involving only BIT variables, however, are efficient. 


fe BL ee 62.8 85 THEN, GOTO EXt}: 


Tests 


The choice of a test can influence the economy with which a program can be 
stated. For example: 


if X = 
THEN 


is more efficient than 
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Invariant Computations 


Any operations that are not associated with the control variable of a loop 
should be moved outside the loop. For example: 


DO: tf = 2 TO: 103 
DO: a -= 1. TO i160: 
CUT 2 AC beak) BCT? 
LOLs © Rela eee 
END; 
END; 


should be rewritten as 


DO | 
Z( 
DO 


2 O23 

We EES 

TO 100; 

= ACI ;d) + BUledds 


e, 
J 
C 


END; 


Structure Layout 


!'f a CHARACTER or BIT string variable within a structure is frequently 
accessed, it should not share a word with another variable. For example, 
consider the following structure of string variables: 


DCL 01 BC ALIGNED, 
02 C1 CHAR(3) UNAL, 
O2 981. BI TC36) UNAL, 
02 C2 CHAR(3) UNAL, 
02 C3 CHAR(1) UNAL; 


The structure BC is represented in storage in the following way: 


0 ) 18 24 
hi ie Te 
Bl (continued) 


The variables share words with one another. Assuming that the variables Bl and 
C2 are frequently accessed, rewriting the structure in the following way 
improves the efficiency of the program: 


DCL 01 BC ALIGNED, 
02 Cl CHAR(3) UNAL, 
02 C3 CHAR(1) UNAL, 
02 B1 BIT(36) UNAL, 
02 C2 CHAR(3) UNAL; 
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The structure BC is now represented in storage in the following way: 


Access of the variables Bl and C2 in this representation is more efficient than 
in the previous representation. 


The rules for laying out aggregates in memory are given earlier, in the 
section on "Internal Representation of PL/I Data". 


Variable Extents 


The use of strings whose maximum length is not known at compile time or 
arrays whose bounds are not known should be avoided whenever possible. bt: .suteh 
a variable must be used within a structure, it should be the last member of the 
structure, as follows: 


DCL 01 C ALIGNED, 
G2 Ci CHARS), 
02 C2 CHAR(4), 
O2 C5: CHARLES), 
02 Ch CHAR(N); 
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Static Global Variables 


A variable that is declared in an outer block and frequently accessed in 
the inner blocks should be declared STATIC. For example, in the program 
fragment: 


Ei? BEGINS 
DCL. UX, YEP EAEDS 
Y i= 2 
E22 BEGIN; 
eee ae ae 
E3: BEGIN; 
ZL -= KS 
END; 
END; 
END; 


If X ts declared as a STATIC variable, the amount of object code for the above 
program is reduced. The declaration of X and Y should be rewritten as: 


DCL, x FIXED STATLCs 
DCL TPE? 


Global and Parameter Variable References 


When an automatic variable declared in a calling block is used frequently 
in the called block, the variable should be assigned to an AUTOMATIC temporary 
declared in the called block. 


Parameters passed by a CALL statement or a_ function reference, if 
frequently accessed, should be assigned to a temporary AUTOMATIC variable within 
the called procedure. The use of temporary storage for parameters is especially 
effective if the parameters are declared with the UNALIGNED attribute, 
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on Argum S 


The use of named constants as arguments of a CALL statement is more 
efficient than the use of literal constants. Consider the following program 
fragment: 


DCL SUG2Z ENTRYCFIAED, FIXED); 
DCL CONST2 FIXED INT STATIC INIT(2), 
CONST3 FIXED INT STATIC INITC3); 


CALL SUB2(CONST2,CONST3) ; 


CALL -SUB2(2, 375 


The statement with the named constant arguments CONST2 and CONST3 is more 
efficient than the statement with the literal constant arguments. 


Initialization 


If avariable is initialized, it should be declared as STATIC if possible. 
Code for the initialization of AUTOMATIC variables must be executed on-~ each 
entry to the block or procedure. 


Labels 


Avoid the use of unnecessary labels in a program. Labels are sometimes 
used to indicate a program note rather than a transfer point. The compiler’ can 
perform better optimization on a series of statements if the statements are not 
broken up by labels. 


Concatenation 


Unnecessary use of concatenation should be avoided because concatenation 
Operations are time-consuming. 


Stream Input-Output 


In stream input-output, use one statement with a long data list rather than 
several input-output statements. Each input-output statement requires linkage 
and, therefore, has an associated overhead. 


Temporary Work Files 


The use of ASCII is more efficient than the use of BCD in temporary stream 
work files. 
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Edit-Directed Input-Output 


For stream input-output, edit-directed input-output is more efficient than 
either list- or data-directed input-output if the GET or PUT statement specifies 
more than one item. 


Stream D Lis 


In stream input-output, a single long item rather than a sequence of short 
items, should be used in the data Jlist whenever possible. Consider, for 
example, the following program fragment: 


DCL 01 C ALIGNED, 
02 C1 CHAR(2) UNAL, 
02 C2 CHAR(6) UNAL, 
02 C3 CHAR(C16) UNAL, 
02 Ch CHAR(20) UNAL, 
02 C5 CHAR(36) UNAL; 
DCL STR CHAR( 80) ALIGNED DEF(C); 


GET. *LISTUSTR? 


GET LIST( CL, C2705,6%, CS)% 


Buffers 


For INDEXED or REGIONAL file organization, the number of buffers allocated 
determines the actual amount of data transmitted to and from external files. 
The allocation of sufficient buffer space minimizes the amount of time spent 
transferring data. 


RULES FOR IMPROVING STORAGE EFFICIENCY 


The rules in this section are useful for improving the storage efficiency 
of a PL/I program. 


Alignment 


In order to minimize the amount of storage used (at the expense of access 
time), use the UNALIGNED attribute for variables within a structure. 


Consider the case in which a large number of tables are allocated in 
storage at execution time. The table has the following declaration: 


DCL 01 TABLE ALIGNED BASED, 
U2 AL. FIXED, 
OF XZ FERED; 
02 Bl bi rea7, 
02 C1 CHAR(3), 
O02. C2 LAARLS?, 
O02 G3. CHARLES )3 
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The storage layout for the above structure occupies seven words, as follows: 


TTITTTE TT T TT 
Xl (supp ] 
ee EL EE LELCE 


supp ] 


ITTTTTITIRIT TATE TTTITT TTT 
Bet nee 
RE Oe 


SUDP 


C3 (cont) TTTITIFTTITITITTITTITITIITEIT IT 


supp] 


Each execution of the statement 
ALLOCATE TABLE SETCP)s 


allocates seven words and sets the pointer variable P to point to the _ starting 
address. However, if the variables of the structure TABLE are declared to be 
UNALIGNED, the variables are stored to minimize storage: 


DCL O01 TABLE ALIGNED BASED, 
G2 Xl FIXED UNAL, 
02 X2 FIXED UNAL, 
OZ BI-BITCS) UNAL, 
02 Cl CHAR(3) UNAL, 
02 C2 CHAR(3) UNAL, 
02 C3 CHAR(5) UNAL; 


The storage layout for the above declaration occupies only four words, = as 
follows: 


C3 (continued) 


The second representation of the structure TABLE saves three words per 
structure. If many TABLES are to be allocated, then the saving is substantial. 


| 
| 
| 


Detailed rules for the storage layout of variables are given earlier in the 
section on the "Internal Representation of PL/I Data". 
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Static Variables 


Variables declared with the STATIC attribute are allocated when the object 
program is loaded and remain allocated throughout the activity. The use of the 4 , 
STATIC attribute, therefore, should be avoided whenever possible if storage 
efficiency is the principal consideration. 


File Organization 


lf a program uses only one or two of the three possible types of file 
organization, then the specification of the file organization in the ENVIRONMENT 
option of the file declaration is more efficient than the specification of the 
organization on control cards at execution time. 


The cost of binding and allocating each external variable is’ high. This 
cost can be reduced by gathering several external variables together into a 
structure. Consider the following declarations: 


DCL CXA1,%2,.4%3). FLAED EXT STATIC; 
DEL. CPipPenPsy Pa? “PIRQVERT. STATICS 


A more efficient representation of the above is: 


DCL O01 LINK EXT STATIC, ) 
OZ XL FLXED, wo 
02 X2 FIXED, 
O2 X5- FIXED, 
U2 .PL PPR, 
02: P2> PUR; 
OZ: PS PRR; 
O02 P& PTR; 


This also reduces the number of separate labeled common regions because a 
separate labeled common region is created for each external static declaration 
statement. A maximum of 63 labeled common regions is permitted per external 
procedure, 


D -Dir d |nput-Outpu 


The use of the DATA option in stream input-output without an explicit list 
of variables requires the entire symbol table to be kept in storage during the 
execution of the program; therefore, it should never be used without a list. 
Even with an explicit list of variables, the cost is considerable. The use of 
the DATA option should be confined to debugging. 


14-14 DEO4 


Input-O | 


Whenever possible, input-output statements should be confined to ae single 
block in a program. The system allocates storage within each block containing 
input-output statements for. an input-output interfacing facility. I f 
input-output statements appear in more than one block, storage is allocated in 
each block for the interfacing facility, and the resulting amount of storage for 
the program is increased. 


Work Regions for Files 


When an INDEXED or REGIONAL file is used, the proper size for the work 
region should be calculated, using the formulas given earlier in the sections on 
"INDEXED Organization" and "REGIONAL Organization" respectively. The 
specification of the proper size for the work region on the $ USE control card 
avoids the allocation of unnecessary space. 
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SECTION XV 


COMMON PROGRAMMING ERRORS 


This section contains remarks on some of the most common programming errors 
made in the use of PL/I. Some of the errors described here are detected by the 
compiler. However, some of the errors are undetectable at compile time, and 
their occurrence during the execution of the program produces invalid results or 
interruption of the flow of control of the program. Often, this type of error 


arises from a misunderstanding of the rules of PL/I and is, therefore, difficult 
to resolve. 


The common mistakes are listed according to the Following classifications: 


Program constructs 
Program structure 
Program control 
Initialization 
Evaluation 
Conversion 
Procedure calls 
Input-output 


The errors in each of the above classifications are described and, where 
necessary, illustrated by an example. The classification given here is intended 
to .aid the reader in locating a topic of interest; however, like most 
classifications, the above one is somewhat arbitrary. Moreover, the list of 
common errors given here is not to be considered, in any sense, complete. 


Discussions of programming style appear throughout the PL/I Reference 
Manual, usually under headings of the form "Guidelines for ... ". Some of the 


discussions point out features of PL/I that are especially susceptible to 
programming errors. 


PROGRAM CONSTRUCTS 


Some reminders related to the basic constructs of a PL/I program are’ given 
in the following paragraphs. 
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The representations of some characters in the PL/I character set depend 
upon the code used. The representations for these characters in ASCII, BCD, and 
EBCDIC are given in the following list: 


Representation 


Character ASCIL BCD EBCDIC 
OR ! ! | 
AND & & & 
NOT A t ‘ 
break - Fs e 
quote ers gad Tepe : 


concatenation 1! 1! | | 


Reserved Character Combination 


A program or data card with the character '$' in Column 1 and the blank 
character in Column 2 can be mistaken for a GCOS control card. Therefore, this 
sequence of characters in the first two columns of a card should be avoided. 


Confusion Between Break and Minus 


The statement 
MACHINE = H-6000; 


is interpreted as the assignment to’ the variable MACHINE of the difference 
between the variable H and the constant 6000. If H-6000 is to be interpreted as 
a variable name containing a break character, the statement must be written as 
follows: 


MACHINE = H-6000; (in BCD) 
MACHINE = H_6000; (ih ASCLI and EBCDIC) 
Confusion Between Assignmen nd Comparison rators 
The character '=!' is used both for assignment and for comparison. In the 


following statement, the first character '=' is used for assignment and_ the 


second, then, for comparison: 


The above statement is equivalent to the statement: 


IF B = C THEN A = '1'B ELSE A = 'O'B; 
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Multiple assignment is accomplished by commas separating the identifiers to 
be assigned. If the above statement is to be a multiple assignment, it would be 
written: 


A,B = C; 


This has the effect of assigning the value in C to both A and B. 


Alphabetic PICTURE characters must be given in upper case even when the 
program is input directly in ASCII from a terminal. For example, the following 
declaration is incorrect: 

DCL X Prec: "saaa's 
The correct form of the above declaration requires the PICTURE characters to be 


in upper case, as follows: 


DCL. X PIC *AAAA’ ; 


Decimal Point in a Pictured Character String 


The PICTURE character 'V' indicates a scale factor and does not. occupy 
storage. On the other hand, the PICTURE character '.' is an editing character 
and does not indicate the scale factor. Consider, first, a program fragment 
that uses the 'V' character in the declaration of CHARGE: 


DCL CHARGE PICTURE '"'S999V9'"'; 
CHARGE = 123.4; 
PUT LIS TCCHARGE) 3 
The execution of the PUT statement produces the following output: 
+1234 


Consider, next, a program fragment that uses the '.' character in the 
declaration of CHARGE: 


DCL “CHARGE FICTURE “S999,90"; 
CHARGE = 123.4; 
PUT LIST(CHARGE) ; 


The execution of the PUT statement produces the following output: 


tO12 3 
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To output the true value of CHARGE, -the characters 'V' and '.' must. be 
adjacent in the declaration. For example: 


DCL CHARGE PICTURE "S999V.9"'s3 

CHARGE = 123.43 

PUT LISTCCHARGE); 
The execution of the PUT statement, in this case, produces the correct result, 
namely: 


sn We a 


The characters '#' and '@' cannot be used in an identifier. The length of 
an external name is’ limited to six characters. The length of a file name is 
limited to five characters. 


Conflict Between Built-In Function and Procedure Names 


If a built-in function is used and not declared, a conflict can occur, as 
follows: 


TRUNC: PROC(Z) RETURNS(FIXED); 


Y = TRUNC(X); 
END; 


Since the built-in funtion TRUNC is not declared, the procedure TRUNC in this 
example is assumed to be recurSive. 


PROGRAM STRUCTURE 


The unintentional omission of a delimiter is a common error in- program 
structure. The effect of amissing comma, semicolon, or parenthesis is well 
known. A missing or misplaced END statement affects the entire program meaning. 
The effect of the omission of comment delimiters, quotation marks, and_ ELSE 
clauses are described in the following paragraphs and a recommendation about the 
use of the END statement for the multiple closure of blocks is made. 
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Unmatched comment delimiters can produce an unexpected interpretation of 
the program by the compiler. Consider the following example: 


/* COMMENT: CALCULATE SPEED 
X = YuuxZ**23 
/* COMMENT: CALCULATE TIME “*/ 


The unintentional omission of the closing comment delimiter '*/' on the first 


line of this fragment results in all three lines being taken as comment. The 
assignment on the second line, therefore, is never performed. 


Nested comments are not allowed. The closing comment delimiter of the 
nested comment prematurely terminates the enclosing comment: 


/* COMMENT: IN THIS CASE 
X J*- THE SPEED. #7 
IS REPLACED BY AN ESTIMATED VALUE */ 
The comment is terminated at the end of the second line of the above fragment. 


The third line is not considered to be a comment and the PL/I compiler attempts 
to interpret that line as a PL/I statement. 


Ud Ss 


In order to preserve the pairing of quotation mark delimiters for character 
strings, any quote within the string must be replaced by a double quote. 
Consider the following text: 


HE SAID, “THE CAR WON'T’ GO". 


When this text is represented as a character string constant, the internal 
quotes are replaced by double quotes as follows: 


VE oA lg) "THe CAR WONT? T GO" oP 


Thus, the pairing of the quote delimiters is preserved. 
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M hi ELSE Clauses 


The compiler associates an ELSE clause with the closest previous unmatched 
IF statement. To get the correct sequence of control, it is sometimes necessary 
to include a null ELSE clause. For example, to assign the value 1 to X if both 
Bl and B2 are true and the value 2 to X if Bl is false, a null ELSE clause is 
required as follows: 


be Ba 
THEN IF B2 
THEN X = Ls 
ELSES 
ELSE A= 23 


If the null ELSE clause is omitted, then the ELSE clause is associated with the 
closest previous IF, as follows: 


aed: 2 
THEN IF B2 
THEN X 


a3 
ELSE X 2 


? 


When the ELSE clause is associated in this way, the value 1 is assigned to X_ if 
Bl and B2 are both true and the value 2 to X if Bl is true and B2 is false. 


Multi losure of Blocks 


The use of an END statement with a label to close a series of nested 
PROCEDURE blocks, BEGIN blocks, or DO-groups can introduce an obscure error. 
Consider the following program fragment: 


Pl: PROC; 


PZ: PROC; 
pO. PS 1 TO WN: 
ACI) = BCI+#1); 
Cli). 1s CCl wes 
, ee SS 
END Pl; 
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The END statement with the label Pl is intended to close the PROCEDURE block Pl 
and the internal procedure P2. However, the END statement for the DO-group was 
inadvertently omitted, and, therefore, the END statement closes the DO-group as 
well as the above mentioned procedure blocks. 


If blocks are closed explicitly by END statements without a label, = any 
missing END statement is detected by the compiler. The use of END statements 
for multiple closure of blocks tends to obscure the structure of the program and 
is, therefore, not recommended. 


PROGRAM CONTROL 


Some critical features of program control are described in the following 
paragraphs. 


QPTIONS(MAIN) Attribute 


Only one procedure in a program can have the OPTIONS(MAIN) attribute. At 
execution time, control is passed to the procedure declared with that attribute. 


Transfer of Contro] 


A GOTO statement that is outside a given PROCEDURE block, BEGIN block, or 
iterative DO-group cannot transfer to a label that is inside the block or group. 
The following fragment contains such a transfer and is, therefore, invalid. 


Plt  <PROC: 


GOTO A; 
p2 PROC; 
A: 3 
END; 
END; 
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A PROCEDURE block is executed only when it is invoked by a CALL statement 
or a function reference. A BEGIN block is executed when control reaches the 
BEGIN statement, either from the preceding statement or from a transfer to the 
label of the BEGIN statement. Consider the following program fragment: 


Pis PROC; 


GOTO A; 
GOTO B; 
A BEGIN; 
END; 
B PROC; 
END; 
END; 
The first transfer statement is correct and as a result of its execution control 
is transferred to the block labeled A. The second transfer statement is 
incorrect. To execute the procedure B, a CALL statement must be used. lf 
control is not explicitly transferred to the BEGIN block in the above example, 
it is executed when control passes to it from the preceding statement. The 


PROCEDURE block, however, is not executed unless it is explicitly invoked. 


Changing the Index within a DO-Group 


If the index of an iterative DO-group is changed within the DO-group, the 
index may never exceed the limit and the program may _ loop. Consider’ the 
following program fragment: 


pO f = 2°10: 20; 
PUT BREST CUXCL)> DO YL =. 28o 10)3; 
END; 
The index |! in this example is reset on each execution of the group and, 


therefore, never exceeds the limit. 
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“>> Misuse of LABEL or ENTRY variables can cause errors that are difficult to 
| trace. Consider the following program fragment, in which the use of ENTRY 
variables causes the mechanism for block activation to be disrupted: 


Pi: PROC OPTIONS(MAIN); 
DCL EV ENTRY VARIABLE; 


CALL E23 


OUT1: CALL EV; 


E2: PROC; 


E3: PROC; 


The statement 
CALL. EV 


attempts to call the procedure E3, which is nested within the procedure E2. 
However, at the time of the call, E2 is no longer active and therefore, the call 
is not valid. 


INITIALIZATION 


Misunderstanding of the effect of initialization and the time at which 
initialization activities occur often gives rise to programming errors. Some 
remarks on this type of error are given in the following paragraphs. 
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If a variable is accessed before a value has been assigned to the variable, 
the program is in error and its continued execution is undefined. 


No variable should be expected to be initialized unless it is declared with 
the INITIAL attribute. If an AUTOMATIC variable is declared with an INITIAL 
attribute, then the variable is initialized to that value upon each activation 
of the block in which it is declared. If an AUTOMATIC variable is declared 
without an INITIAL attribute, then the value of the variable is undefined upon 
each activation of the block. 


An attempt to write out, using STREAM-oriented data transmission, variables 
that have not been initialized can cause a CONVERSION error to occur. 


Allocation of Variables 


An AUTOMATIC variable in a block is allocated when the block is activated. 
Consider the following program fragment: 


Ps PROC; 
DCL N FIXED: 
N = 10; 

PZ: BEGIN; 


DEL. CL GHARCN) s 

DCL C2 CHAR(N) BASED; 
N = 20; 

ALLOCATE C2 SETCR?: 


END; 


The AUTOMATIC variable Cl is allocated when the block is activated. Since the 
value of N is 10 when the block is activated, ten characters are allocated for 
Cl and remain the allocation for Cl throughout the block's execution. The 
variable C2 is allocated by the ALLOCATE statement. Since the value of N is 20 
when the ALLOCATE statement is executed, twenty characters are allocated for C2. 
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r m ao iin for DO-Gr 


Increments and limits for DO-groups are computed upon entry to the 
DO-group. Consider the following program fragment: 


a PROC; 
J = 10; 
DO } -@ 1 TO 4k 
J = 20; 
END; 
END; 


The limit of the DO-group is evaluated upon entry and is, therefore, 10. 
Although the value of J is changed within the DO-group, the value of the limit 
is unchanged and consequently, the DO-group is executed ten times. 


External Names 


The declarations of an external mame must be identical in all external 
procedures which become part of a single execution unit. Consider, for example, 
the declaration of the external variable, M, in two external procedures: 


Pls PROC; 
DCL M FIXED EXT INITCI; 


END; 


PZ: PROC; 
DCL M FIAED EXT? 


END; 


The two declarations of M differ: in one case M is initialized and in the other, 
it is not. The above procedures, therefore, are incorrect. 
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E ressions for D riab 


The extents of BASED variables must be Known at the time the variable is 
allocated. Consider the following program fragment: 


Pies -PROC> 
DCL 01 BV ALIGNED BASED(P), 
O02 N FIXED, 
02 CH CHARCN): 


ALLOCATE BV; 


END; 


The length of the character string variable CH is given by N, a member of the 
same structure. Therefore, when the ALLOCATE statement is executed, the value 
of N and the length of the character string CH are undefined. To obtain the 
correct result, the REFER option should be used, as follows: 


DCL 01 BV ALIGNED BASED(P), 
U2 iN FLXED; 
02 CH CHAR(M REFER(BV.N)); 
The value of M determines the maximum length of the character string and is 
assigned to BV.N at the same time that BV is allocated. Subsequent references 
to the BASED variable CH make use of the value of BV.N. 


i tion _F- ors Th TRA TT ributes 


In an INITIAL attribute, a parenthesized expression can be used to treat a 
single value as a sequence of values. Consider, for example, the declaration: 


DCE. XS) FIXED INIT tS )2>> 


This declaration initializes each of the three elements of X to the value one. 


However, a problem arises when the initial value is a string constant. 
Consider the declaration: 


DCE YCSy CHARCZ0). INITCCS2-%"0¢ 
The parenthesized expression in this declaration is a factor that denotes’ the 


repetition of the sequence in the string constant the specified number of times 
to derive the complete constant. The above declaration is equivalent to: 


DCL. YC3) CHARC20). INITU'ARS" 2 
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Since this declaration provides only one initial value when three initial values 
are required, the declaration is invalid. To initialize the three values to a 
single X, the following declaration must be used: 

DCE ¥C3) CHARC20) PNITCC3IC1) Xx: 
In this statement, the parenthesized expression '(1)' is the factor treated as 


part of the string constant, and the parenthesized expression '(3)' is treated 
as a replication factor for the initial values of the three-element array. 


EVALUATION 


The following paragraphs list errors that arise from misunderstanding of 
the order of evaluation or the behavior of the SUBSTR built-in function. 


Multiple Assignments 


Misunderstanding of the order in which multiple assignments are _ executed 
sometimes creates a programming error that is difficult to trace. Consider the 
following program fragment: 


PL? PROC; 
DCL (ACS IG.12: LAER; 


END; 


After the execution of the multiple assignment statement, the array elements 
have the following values: 


A(1) 2 
A(2) 2 
A(3) 0 
AC 4) 0 
A(5) 0 


The multiple assignment statement is equivalent to the following sequence of 
statements: 


TEMP = | + 1; 
ACI) = TEMP; 
| = TEMP; 
AC |) = TEMP; 


bs oa hos 
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Evaluation Order 


Misunderstanding of the order in which expressions are evaluated can lead 
to errors that are difficult to find. The following list gives some common 
unparenthesized expressions. The order of evaluation for these expressions is 
made explicit by the use of parentheses. 


Expression Evaluation Order 
A=B! C LA = B) 1 -C 
B.C 4: 0 Bt to aD) 

eae Se = Ge Om & CA > By AC 

| ae cae ae © cA? Bd 2 f 
A**B*x*C A**(B**C) 


Parentheses can be used to change the order of evaluation when required. 


SUBSTR Built-In Function Arguments 


The arguments of the SUBSTR built-in function that specify the starting 
position and the length must be valid for the specified string. Consider’ the 
following example: 


P: PROC; 
DEL ©L. CHARCIZ2> 
DCL €2(10) CHAR(4&); 


UO “f  Sk Toe 26 
C2¢h)) = SUBSTRCVC1, 1, 4)3 
END; 

END; 


The assignment statement in the above example is valid for the values of | from 
One to nine. However, when | has the value ten, the SUBSTR function attempts to 
access the thirteenth character of a twelve-character string and the 
SUBSCRIPTRANGE condition is raised if the condition is enabled. If the 
SUBSCRIPTRANGE condition is not enabled, the program is in error and its 
continued execution undefined. 
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An assignment to a varying string by the SUBSTR pseudo-variable does not 
alter the control word that holds the current length of the string. Consider 
the following example: 


DCL C1 CHAR(6) VARYING; 


C1 - As 
SUBSTR(C1,2,3) = "BCD": 
PUT LIST(C1); 


The length of the varying string Cl is determined to be one by the first 
assignment statement. Since the SUBSTR pseudo-variable does not alter that 


length in the second statement, the PUT statement outputs the single character 
| ae 


Only another assignment into or concatenation onto a varying string will 
modify the current size of the string. 


CONVERSION 


Some of the most difficult errors in PL/I programs are related to the 
effect of conversion. Conversions should be avoided, whenever. possible. The 
resulting program is clearer and more efficient. Some conversion problems are 
described in the following paragraphs. 


d-Point Divi 


The precision of a constant affects the precision of the intermediate 
results. Consider the following program fragment: 


UGG A FTAED DECC 3,1) 
K. @ AU + 153 


The precision of the intermediate result is (59,58). In PL/I, this precision 
causes the FIXEDOVERFLOW condition to occur. For general fixed-point arithmetic 
expressions, the DIVIDE built-in function, which permits the programmer to. give 
the precision of the result, should be used. For constant values, a single 
constant with a decimal point should be used. Thus, the above assignment 
statement should be written as: 


X = 10.333333 
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Loss of Precision in Conversion 


According to the rules of PL/I, conversion occurs whenever the data types 
of the operands of an expression differ. In some cases, the conversion results 
in the loss of the value of the result of the operation through truncation. 
Consider the following program fragment: 


DCL X FIXEDCS) INITC1); 
DCL BL, Ba) BIT th) 


w 
NO 
a 
=< 
+ 
. 


The execution of the first assignment statement assigns the value '0001' to Bl. 
The execution of the second assignment statement involves’ addition. The 
precision of the decimal constant, 1, converted to binary is (5,0). The 
precision of the result of the addition operation, then, is (6,0). The value of 
the addition operation '000010' is truncated to four bits for assignment to B2. 
Therefore, the value '0000' is assigned to B2 as a result of the execution of 
the second assignment statement. 


To obtain the correct result the built-in functions FIXED or BIT can be 
used, as follows: 


O2 = FIAEDCASL, 4):3 
or 
BZ = BITCE PKEDCX*1,3),4)% 
Fixed-Poi Arithmeti oO Char Yr Co sion 


Assignment of a fixed-point arithmetic value to a character string requires 
three more characters in the string than there are digit positions in the value. 
Consider the following example: 


DCL C CHAR(6) STATIC INIT(123456); 


The initial value of C, as specified in the above declaration, is: 


'6bb123" 


where $ indicates the blank character. 


To obtain the desired result, the initial value should be given as a 
character string constant, as follows: 


DCLG CHARCG) STATIC ENDTC" 123856") ; 
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PROCEDURE CALLS 


Some common programming errors made in the invocation of procedures. and 
function references are described in the following paragraphs. 


If the storage type of an argument in a CALL statement or function 
reference is not identical to the storage type of the parameter, the argument is 
passed by-value. The value of a by-value argument cannot be changed by any 
action of the procedures. Consider the following program fragment: 


ape PROC; 
DOL A -BlTCs7s 
DCL E2 EXt ENTRYCBITCS) ALTGNED) s 
X = "0OO1"B; 
CALL E2¢(xX)s 
IF X = "101"B THEN GOTO NEXT; 


NEXT: END; 
E2:  PROC(B); 
DCL B BIT(3) ALIGNED; 


Bo 2: "201": 
RETURN; 
END; 


Since no alignment is specified for the variable X in its declaration, it 
acquires the default alignment UNALIGNED. Therefore, the storage type of the 
argument X is not identical to the storage type of the parameter B. The 
argument is passed by-value and after the execution of the procedure E2, the 
value of X is unchanged. The test on X following the procedure call, therefore, 
fails. 
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If an argument is enclosed in parentheses, it is passed by-value. Since 
the generation of storage associated with the parameter is not the generation 
occupied by the original argument, any assignment to the parameter by the 
procedure has no effect upon the value of the argument. 


Consider the following program fragment: 


Pil: PROC: 
DCL P PTR ALIGNED; 


CALL SUB((P)); 


SUB: PROC (Q); 
DCL (Q,R) PTR ALIGNED; 


END; 


The execution of the procedure SUB does not affect the value of the pointer 
variable P., 


F i R i thou m 


A function reference without an argument list must be followed by a pair of 
parentheses, indicating an empty list. In this way a function reference is 
distinguished from an entry constant. Consider the following program fragment: 


DCL FUNC ENTRY() RETURNS(CHAR(10)); 
DCL V ENTRY; 
DCL C CHAR(10); 


FUNC; 
FUNC(); 


O<ce - 
uo 


The first assignment statement assigns the entry constant FUNC to the entry 
variable V. The second assignment assigns the result of the function FUNC to 
the CHARACTER string variable C. 
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Multiple Entry Points 


When a procedure has more than one entry point and the different entry 
points have their own parameter lists, any statement within the procedure that 
refers to parameters from different lists is in error. For example, consider 
the following program fragment: 


Giz -PROC(A,B): 


G2:  ENTRY(X,Y); 


C =A+ X3 


END: 


The assignment statement in the above example is in error because it refers to a 
parameter, A, from one list and a parameter, X, from another list. 


The extent of a parameter can be declared with either a constant or. an 
asterisk. The following declaration of a parameter is wrong because the 
parameter extent is declared to be a variable: 


Pl: PROC(A,N); 
DCL ACN) FIXED DEC(6); 


END; 


INPUT-OUTPUT 


Common errors related to input-output are described in the following 
paragraphs. 


15219 DEO4 


Input-Output Lists 


An iterated input-output list must be parenthesized. The following GET 
Statement is syntactically incorrect. 


Sel. ELSTUACE DS, 2). DO]. = 2°70 ND 


The above statement should be written as: 


GET Lis Teeact).. bhi p0-" > = 2-70. NI 
Control Format Items 
A control format item is executed only if it precedes a data format item 


that is paired to a data item. Consider the statement: 
PUT EDIT(CA,B) 
CFCR) ACS) AF( Sd A057)" 


In this statement, the control] format item, X(3), is not executed. 


Control Options 


Control options are always executed before data transmission regardless of 
their position with respect to the data specifications. For example, the 
statements: 


PUT SRIP EDETCAC YY 
(hCS)7, 402), FC5))5 
and 


PUT EDI TCA, Y2 
CEC SIZACZ IVF CSI) SKIPS 


are equivalent. Both statements skip a line before printing X and Y in the 
EDI T-directed format. 


Input Strings 


A CHARACTER or BIT string format item must include the string size on 
input. The size specification is not required for output. 
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Mixed Transmission 


If a file is read using both list- and edit-directed data transmission, the 
format of the file must be taken into account. Consider, for example, the 
following program fragment, which contains two types of data transmission: 


DEL % FRAED DECtG 23 
DCL Z CHAR(4); 


GET LIST(X); 
GET EDIT(Z) 
(ACK); 


When this program reads the input stream: 


12366, BABC 
the following results are obtained for X and Z: 


X 123 
Z "Bb, BA! 


That is, after execution of the first list-directed GET statement, the next data 
item will begin with the first character following the blank or comma that 
separates it from the previous data item. 


Page and Line Size 


The specifications PAGESIZE and LINESIZE for a file are given as options on 
the OPEN statement for the file. These specifications are not part of the file 
declaration. 


In RECORD-oriented input-output, code conversion is not performed. Since 
the internal code for PL/I is ASCII, RECORD-oriented input-output cannot be used 
to transmit data to peripheral devices that accept only BCD. Therefore, 
STREAM-oriented input-output must be used to transmit data from the card reader 


or to the line printer. 


ontrol Cards for INDEXED d REGIONAL Files 


'f a file with INDEXED or REGIONAL organization is used in a program, the 
work region and file parameters must be given at execution time on control 
cards. The required control cards are described in the sections of this manual 
dealing with file organization. 
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SECTION XVI 


SOLUTION OF A PROBLEM IN PL/I 


The variety of language features available in PL/I gives the user. great 
flexibility in the solution of problems. To solve a given problem, a number of 
different approaches can be taken. 


This section defines a problem and then illustrates two possible programs 
for the solution of the problem. The first solution is a hastily-written 
program for the programmer's own use. The second solution iS a= program 
developed for use in a production environment. 


The problem is simple and the programs are short. Aside from this unreal 
simplicity, the problem represents ae realistic application of PL/I. The 
programs illustrate the features of the language and the freedom the programmer 
has in the solution of a problem. In addition to the solution programs” given 
here, there are other equally valid solutions to the problem. The suitability 
of a program depends upon the constraints under which it is written. 


EFINITION OF THE PROBLEM 
The problem to be solved is defined as follows: 


Input a value, calculate the exact value of its factorial, 
and print the value with the calculated factorial. 
The factorial is a mathematical function that is defined by the following 
formula: 
factorial(n) = n(€n-1)(n-2)...1 
where n is an integer greater than zero, and 
factorial 02 = 1 
The calculation of factorials is a simple problem with some _ interesting 
properties: 
& The factorial is defined only for non-negative integers. 


® The factorial increases rapidly. 
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The two programs” given here calculate the factorial in approximately the same 
way. Both programs use binary arithmetic to obtain an efficient solution and 
fixed-point arithmetic to obtain maximum binary capacity. The programs, 
however, are very different in their handling of input-output. 


FIRST SOLUTION 


The first solution of the defined problem is a program written for. the 
programmer's own. uSe. The program is' written using list-directed input to 
obtain the values for which the factorial is to be calculated. Since the only 
user of the program is the programmer himself and since the program is to be run 
only a few. times, no special provisions are made to detect and handle illegal 
input. If a condition occurs as a result of an input value, the default ON unit 
is invoked and the execution of the program terminated. For convenience, the 
programmer makes use of the default ON unit for the ENDFILE condition to 
terminate the run when the input values are exhausted. 
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The 


deck setup for the first solution is given in Figure 16-1. 


the output values are of interest to the programmer, 
omitted and warning messages suppressed. 


ARAAHA SH Ue 


S_ 16 

SNUMB JOB16 
IDENT 

USERID 

OPTION PL1,NOMAP 
Pid SEVERITY2 


PROC OPTIONS(MAIN); 
DOE oT FRAEDS 
DCL (SYS INV SYSPRINTD “FLEES 


PUT PAGE LISTC™EXACT VALUES.OF FACTORIALS"); 


PUT SREP LISTOM I, “FACTORIALCT):")¢ 
GET LS tla 
PUT SRP LESTCL, FACT CI 23 
GOTO: LOOP’ 
PROC(ARG) RETURNS(FIXED(71)); 
DCL ARG FIXED; 
DEL. RES FIXEDC7 1); 
DCL LP TAEOs 
IF ARG = 0 THEN RETURN(1); 


RES = > 
DO | = 1 TO ARG: 
RES = RES#¥lI; 
END; 
RETURNCRES) ; 
END; 
END; 
EXECUTE 
LIMITS 25: SOK RK 
DATA |* 
pee’ 
ENDJOB 


the optional 


Figure 16-1. Deck Setup for First Solution 
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listings are 


DEO4 


Output Listing 


The complete output listing for this run is given in Figure 16-2. Because 
the programmer made use of the default ON unit for the ENDFILE condition, an 
error trace-back and register list are given at the conclusion of the execution 
of the program. Following this information, the information output on SYSPRINT 
is listed. 
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Discussion 


This solution to the problem, although satisfactory for its stated purpose, 
has defects. A positive non-integer value is converted to an integer’ value. 
For example, the input value 8.83 produces the following output line: 


s 362880 
Negative values are accepted and processed. Since the program is written only 
for positive integers, the following erroneous output line is produced for’ the 
input value -6: 
-6 1 
Input values that are invalid or out of range terminate the run. If legitimate 


input values follow such invalid inputs, the legitimate values are not 
processed. Some examples of values that terminate processing are given here: 


Input Value Condition Raised 
Al CONVERSION 
23 F!1XEDOVERFLOW 
b35.1073 SIZE (in the runtime 


input routines) 


In addition to the defects noted above in input processing, the output, 
although unambiguous, is not well formatted. Yet, clearly, the defects 
mentioned are not important if the purpose of the program is to compute several 
factorials for the programmer. 


SECOND SOLUTION 


The second solution to the defined problem is a program to be released for 
general use. The input format, therefore, must be carefully defined and any 
departure from the input format’ reported. Invalid input values must be 
detected, reported, and skipped so that the processing of valid values can 
continue. 


The programmer defines the format to be one input value per card. The 
input value occupies the first two columns of the card and the remaining columns 
of the card must be blank. This input format is quite rigid, but it guarantees 
that only legal input values are processed. Invalid input values are detected 
and a descriptive message printed. 


Deck Setup 


Because the program is destined for production use, the programmer obtains 
a complete set of output listings for his files. The deck setup for the second 
solution is given in Figure 16-3. 
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a ; 
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8 16 
SNUMB JOB18 
IDENT 

OPTION PEL 
PLL LIST 


/* FACTORIAL PROGRAM 


PROGRAM TO COMPUTE THE EXACT VALUES OF GIVEN FACTORIALS. 
INPUT VALUE MUST BE BETWEEN O AND 22, INCLUSIVE. 

INPUT CARD MUST CONTAIN TWO DIGITS FOLLOWED BY 78 BLANKS. 
INVALID INPUT IS DETECTED AND NOTED IN THE OUTPUT. 
EXECUTION CONTINUES AFTER INVALID INPUT CARD. 

NORMAL TERMINATION IS AT THE INPUT END-OF-FILE. */ 


P2: PROC OPTIONS(MAIN); 
DCL. oF SPL REDS 
DCL. S CHARC7S8) + 
DCL. CUSYSIN,SYSPRINT) FILES 
DCL (CENDFILE,CONVERSION) CONDITION; 
/* ESTABLISH ON-UNITS «/ 
ON ENDFILECSYSIN) GOTO EXIT; 
ON CONVERSION BEGIN; 
PUT EDIT('--","-- (BAD INPUT VALUE SKI PPED)"') 
(SKIT P,ACZ 34021) 7A 
GOTO LOOP; 
END; 
/* PRINT TITLE AND COLUMN HEADS */ 
PUT EDITC" EXACT VALUES OF FACTORIALS'") 
(PAGE,A); 
PUT -EDITO' to’ FACTOR IALCTO") 
CSKIPL ZAC LG ACLIG ACI ALL: 
co PUT SKIP; 
/* PROCESS GIVEN VALUES *«/ 
LOOP: GET EDITCI,S) 
(SKIP, P"99",A(78)); 
Le oO <= | & | <= 22 
THEN PUT EDITCL,FACTCI 
CSRLP. PLS £1 oe” 021920") 
ELSE PUT EDIT(I1,"-- (INPUT OUT OF RANGE)'"') 
CSKLP, PP ZS X21) A 
ie Soe fea" 
THEN PUT EDITC''CWARNING: COL 3-80 NOT BLANK)"') 
CXC 1) ADs 
GOTO LOOP; 
/* PRINT CLOSING MESSAGE #*/ 
EAT? PUT EDITC"END OF FACTORIAL OUTPUT") 
CSKEPZAD: : 
/* CALCULATE A FACTORIAL */ 
FACTS PROC(C ARG) RETURNS(FIXED(71)); 
DCL ARG FIXED; 
DCL. RES FILXEDC71):; 
OCL K FIXED: 
RES = 1; 
DO K = 2 TO ARG: 
RES = K*RES; 
END; 
RETURNCRES); 
END; 
END; 
y Figure 16-3. Deck Setup for Second Solution 
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(cont) 
1L 8 16 3 
$ EXECUTE Ww 


$ LIMITS 2,40K,-2K 
$ DATA |* 


$ ENDJOB 


Figure 16-3 (cont). Deck Setup for Second Solution 


Output Listing 


The output listing for the second solution consists of 26 pages because it 
includes additional listings requested by the LIST option on the $ PL1 control 
card. The complete output listing is, therefore, not reproduced in this manual. 
However, Figure 16-4 gives the information output on SYSPRINT as a result of the XY 7 
execution of the program. 


EXACT VALUES OF FACTORIALS 
| FACTORIAL(1) 


6 720 
10 3628800 
£2 479001600 

0 1 


“= == SAD INPUT VALUE SRPPPED) 
22 1124000727777607680000 ST Ee 


23 == CINPUT OUT OF RANGE? 
an ~- (BAD INPUT VALUE SKIPPED | 
20 2432902008176640000 (WARNING: COL 3-80 NOT BLANK) 


Soapcermece -- (BAD INPUT VALUE SKIPPED 
ig ~3 (BAD. INPOT, VALUE SKIPPED) 


-- mie BAD ENPUL VALUE SERIPPED 
4 24 


END OF FACTORIAL OUTPUT 


Figure 16-4. Output of Second Solution 
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Input values that are invalid are not printed because such a value _ could, 
in fact, be nonprintable. In this run, the invalid input values were the 
following: 


As previously noted, the input format is very rigid. To enter the input’ value 
‘kh @ cara with: a-*0" In -cotunw Lf and a “h"- In eétumn 2 must be. xiven, 


The input value '202' js assumed to be the value '20', but a warning is 
issued that the remaining columns of the card are not blank. The input value 
'23' is detected by the program as being out of range. 


Discussion 


The second solution to the defined problem is a foolproof program in the 
following sense: i 


® Any departure from the specified input format is noted and a warning 
message printed. 


® The program recovers from invalid input to continue processing valid 
inputs. 


These assertions are supported by the following features of the program: 


@ The only value allowed by the picture is a non-negative integer. 


@ Columns 3 - 80 of the card are checked and any nonblank character in 
those columns causes a warning message to be printed. 


] An ON-unit is provided to handle the CONVERSION condition, which’ can 
be raised by invalid input values. 


S The range of the positive integer value is checked in the program to 
prevent the occurrence of the FIXEDOVERFLOW condition. 
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APPENDIX A 


SERIES 60 (LEVEL 66)/6000 PL/I RESTRICTIONS 


The following restrictions are present in the implementation of PL/I in the 


environment. 


Identifiers 


External Names 


File Names 
Picture Characters 


Peripheral Devices 


Line Size 


BCD Files 


REWRITE Statement 


INDEXED Files 


REGIONAL Files 


DECIMAL Attribute 


INDEXED and 
REGIONAL Files 


ASCII Files 


An identifier cannot contain either the character '#! 
| | 
Or, *H0" 


The General Loader requires that an external name _ must 
be six or less characters in length. Any external name 
of more than six characters will be converted by the 
system (see Appendix F). 


A file name must be one to five characters. 
Picture characters must be given as capital letters. 


The paper tape reader or paper tape punch cannot. be 
used. 


The line size of a file with the PRINT attribute cannot 
exceed 136 characters. 


BCD files cannot be handled with RECORD-oriented 
input-output. RECORD-oriented input-output, therefore, 
Cannot be used for the card reader or line printer 
since these devices accept only BCD code. 


The REWRITE statement cannot be used for SEQUENTIAL 


tiles. 


Embedded keys are the only type of keys in an INDEXED 
file. 


The value of a key in a REGIONAL file must be a 
positive integer. 


The length of the character string appearing in the 
KEYTO option must be exactly 32 characters. 


In the interest of future file compatibility, the use 
of DECIMAL data in RECORD 1/0 content should be 
avoided. It is expected that a future version of PL/I 
wil] use a different hardware representation for 
DECIMAL variables. 


A future version of PL/I will be supported by UFAS 
(refer to the UFAS manual) which utilizes different 
file formats. Present files will require conversion 
for compatibility. 


ASCII! stream files written by the PL/I system and used 
by the COPY and SAVE directives of SRCLIB are presently 
not compatible with time sharing subsystems and other 
users of ASCI! files. : 


A-1 DEO4 


APPENDIX B 


COMPARISON OF SERIES 60 (LEVEL 66)/6000 PL/I AND STANDARD PL/I 


This appendix lists all known deviations of the Series 60 (Level 66)/6000 
PL/I language from the draft standard as of March 1974. When this PL/I language 
was specified, the ANSI/ECMA PL/I standardization committee had not completed 
its definition of PL/I. Any language issue not then resolved by the standards 
committee is marked by the symbol '«', 


Four types of departure from the standard are covered in this appendix, 
namely: 


Features of standard PL/I not in this PL/I 

Features restricted in this PL/I 

Features implemented at variance with the standard 

Extensions 
The reader is assumed to be familiar with the work of the ANSI /ECMA 
standardization committee. 


The Multics PL/I Language Manual (Order No. AG94) specifies a language very 
close to the proposed standard. lt is a semi-formal definition of the Multics 
PL/I language from which this PL/I system was derived. The terminology of this 
appendix is consistent with that of the Multics PL/I Language Manual. 


FEATURES OF STANDARD PL/I NOT IN SERIES 60 (LEVEL 66)/6000 PL/I 


The following features are part of standard PL/I, but are not included in 
this PL/I. 


i ee The BYNAME option in the assignment statement. 
2: The Ty “'t".. Sid -'*R” pietire. characters, 


a The TAB option and TAB format item. In this PL/! the same effect can 
be obtained by control cards at execution time. 


EEATURES RESTRICTED IN PL/| 


The following features are restricted in this PL/I. 


ix A literal constant cannot contain a scale factor (Ft+tn) or a default 
Suppression character (P). 


LD 
L164 


1 


18. 


iS 


20). 


A bit string constant cannot be expressed in octal or hexadecimal, and 
the bit string format has no provision for processing octal or 
hexadecimal. 


Only one prefix subscript is permitted in a label prefix. 


The condition names defined by the language are reserved. A 
user-defined condition cannot have the same name as a language-defined 
condition. 


A condition name cannot have INTERNAL scope. 
Only one attribute set is allowed in a DEFAULT statement. 


The extents of variables with the STATIC attribute must be decimal 
integers. The expressions in the INITIAL attribute for a STATIC 
variable are restricted to optionally signed literal constants, pairs 
of real and imaginary signed literal constants, or the NULL and EMPTY 
built-in functions. 


The label prefix of a PROCEDURE ENTRY, or FORMAT statement cannot 
contain a prefix subscript. 


The STRING built-in function requires that its argument be a scalar or 
an aggregate consisting of either packed bit string data or packed 
character string data. 


lf two structures share storage, their alignment attributes must 
match. 


Only one condition name is allowed in an ON statement. 


All condition prefixes of a statement must precede any label prefixes 
of the statement. 


An AREA variable cannot be used as the index of a DO statement. 


DEFINED variables whose DEFINED attribute contains either ISUBS or 
asterisks cannot be input or output by a GET or PUT statement that 
specifies data directed transmission. 


File constants cannot have the DIMENSION attribute. 


lf the expression of an assignment statement is aereference that 
identifies a scalar string variable, then no target of the assignment 
statement can identify a generation of storage that overlaps’7 the 
generation of storage of the string variable, unless it is exactly the 
same generation. 


Asterisk extents must be used when passing an unconnected array as_ an 
array parameter. An unconnected array is an array whose elements are 
separated from one another in storage by other values. 


When one array shares storage with another array by simple defining, 
the base reference must contain an asterisk for each dimension of the 
DEFINED array. 


The pointer value yielded by the ADDR built-in function applied to a 
parameter is valid only as long as the block activation to which the 
corresponding argument was passed is still active. This restriction 
applies to the case in which the standard option OPTZ is given on the 
$¢ PL1 control card. 


The standard allows an array of scalars to be promoted to an array of 
structures, but this PL/!I does not allow this promotion. 
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Zs A simple or ISUB defined variable must have extents that equal the 
corresponding extents of the base variable on which it is defined. 
The standard allows the extents to be less than or equal to. the 

a, extents of the base variable. 


ie In structure promotion of the form S=R or S+R, this PL/I requires that 
the aggregate type of each member of S match the aggregate type of the 
corresponding member of R. The standard performs aggregate promotion 
for members that do not match. 


a ae The DOT built-in function requires that the precision of its result be 
given in the function reference. 


Pi Both the IGNORE option and the KEY option cannot be given in the same 
READ statement. 


2. The INTO option of a READ statement may not reference a VARYING 
string. 


FEATURES IMPLEMENTED AT VARIANCE WITH THE STANDARD 


The implementation of the following features produces a different effect 
than specified in the standard. 


ie Return from an ON-unit entered by a signal of the AREA condition 
causes the allocation to be re-attempted in the original area, without 
reevaluation of the IN option. 


ae The bounds of an evaluated array expression are always normalized such 
that each Jower bound is one and each upper bound is the number of 
; rans elements in the dimension. 
oe A mismatch between the alignment attributes of a structure and a 


structure parameter descriptor causes the argument to. be passed 
by-value rather than by-reference. The standard ignores the alignment 
attributes of structures. 


4. The STRINGSIZE condition fs disabled by default [In this PL/I, but 
enabled in standard PL/I. 


EXTENS TONS 


The following. features are tneluded in this PL/| but are: not part of 
standard PL/1i. 


Ly An tdentifier can contain the special character "$'. in the case of 
| external names, this character has additional semantics. 


oF Varying length strings can be used in simple and ISUB defining. 


3 The base variable identified by a DEFINED attribute can be a BASED 
variable. 


oe Most restrictions on the REFER option are removed. 


oe Several new built-in functions are implemented. 


“™ 6. The INCLUDE macro is implemented. 
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The LOCAL attribute is allowed in all descriptors. 


BASED variables can be output by a PUT statement that specifies 
data-directed output. 


An IN option is not required in a FREE statement when freeing a 
generation of storage allocated in an area. 


The RECURSIVE keyword is never required in a PROCEDURE statement. The 
system always generates code for a procedure that allows recursive 
calls. 


The UNSPEC pseudo variable allows aggregate arguments. 


Assignments and infix operations can be performed on two arrays7 of 
unequal bounds if the number of dimensions is equal and the number of 
elements in each dimension of one array is equal to the number. of 
elements in the corresponding dimension of the other array. 


A replication factor in a PICTURE can be zero. A zero. replication 
factor indicates that the picture character to which it applies Is to 
be deleted from the normal picture produced by the translation of the 
PICTURE, 


A name declared with the ENVIRONMENT attribute acquires the FILE 
attribute by default. A name declared with the OPTIONS attribute 
acquires the ENTRY attribute by default. The standard does not give 
defaults for these cases. 


The COLUMN option can be used by a GET or PUT statement containing the 
STRING option. 


The standard considers the case in which an array is passed as_ an 
argument to an array parameter that has different bounds but equal 
extents to be an error. This PL/I assigns the argument to an array 
temporary whose bounds are equal to the bounds of the array parameter. 
A picture scale factor is allowed for floating point pictures. 

The REDUCIBLE and IRREDUCIBLE attributes are allowed, 

No delimiter is required between the keywords PICTURE or PIC and_ the 


quoted picture in ae picture attribute. No delimiter is required 
between the letter P and the quoted picture in a picture format. 
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APPENDIX C 


MEMORY REQUIREMENTS 


MEMORY ESTIMATION 


To estimate the memory size required for the execution of a program 
compiled by this PL/I compiler, the following items must be considered: 
The size of the object program to be allocated. 
Storage allocated dynamically at execution time for: 
AUTOMATIC variables 
BASED variables 
CONTROLLED variables 
ON-units 


Library routines provided by the system at execution time. 


The memory required is calculated by adding the requirements of the above items. 


RECOMMENDED PROCEDURE FOR STORAGE USE 


It is often difficult to predict the required memory size due to the 
program logic and input data. However, after the job is executed, the system 
prints the memory size that was actually used, as follows: 


**31K WAS USED TO EXECUTE THIS PROGRAM. 
Therefore, the recommended procedure is to specify a slightly oversized memory 


requirement for the first execution of the job on the $ LIMIT control card. and, 
after execution, to replace that estimate by the actual memory used. 
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MINIMUM MEMORY RE REMENTS 


Approximate minimum memory requirements for different job types are given 
below: 


Job Type Minimum Memory 
STREAM list-directed transmission 27K 
STREAM edit-directed transmission 28K 
STREAM data-directed transmission 30K 
RECORD CONSECUTIVE organization 16K 
RECORD INDEXED organization 20K 
RECORD REGIONAL organization 22K 


The minimums are composed of basic run-time support routines as well as 
input-output support routines. Therefore, job type combinations cannot be 
predicted by simple addition. A job having files of both STREAM list-directed 
and RECORD REGIONAL takes 29K while the combination of STREAM list-directed and 
RECORD INDEXED takes 36K. A combination of STREAM list-directed and 
data-directed needs at least 32K and a combination of STREAM data-directed with 
RECORD CONSECUTIVE needs 34K. 
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CHARACTER CONVERSION TABLES 


This section contains three character conversion tables: 


IBMEL to ASCII Conversion Table (Table D-1) 
GBCD to ASCII Conversion Table (Table D-2) 
ASCII to GBCD and IBMEL Conversion Table (Table D-3) 


The first two tables provide the input conversion rules that = are used for 
creating a PL/I source program and for input data. The third table provides the 
output conversion rules that are used for writing data out to external media. 
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IBMEL 
Character 


blank 


+ ewen =LROOoWM H == 


1s 


WON NUFWNNHNFe O™e 


pw wo fZ2taern6. = TVOTiMoO OWS away I ANe se 


Table D-1. 


IBMEL 
Card 
Punch 


blank 


be a a Os 


ae | 


Character Conversion Table (IBMEL to ASCI1) 


GBCD 
Character 


blank 


+ ewen 2£R0° 0H + == 


~ 


WOcnNOMNFWNHOEe O™-s 


PvyvoZzwZzrxn-xCc—-UAOMMIIAIWPOawN Il Ave oe 


GBCD 
Internal 
Code 


20 
Te 
76 
ie 
=o 
74 
a2 
a. 
35 
xo 
54 
60 
13> 
a2 
a2 
61 
00 
01 
02 
03 
04 
05 
06 
07 
10 
11 
| he 
56 
36 
ibe 
16 
17 
14 
Zu 
22 
23 
24 
Zo 
26 


ASC LA 
Character 


1s + eFeVen ={L0°oH * 


WOonnNMNFWNNHrH O™es 


PBvdEeazaszrAC—_TAONMMIONQWPOaeVNV I Ave ee 


ASCII 


Internal 


Code 


040 
O41 
O42 
043 
O44 
O45 
O46 
O47 
050 
051 
052 
053 
054 
ua9 
056 
057 
060 
061 
062 
063 
064 
065 
066 
067 
070 
071 
072 
073 
074 
075 
076 
077 
100 
LOL 
102 
103 
104 
105 
106 
107 
110 
mA 
YR I 
113 
114 
115 
116 
Lay 
120 
rid 
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Table D-1 (cont). Character Conversion Table (IBMEL to ASCII) 


1 BMEL IBMEL GBCD GBCD GBCD ASCII ASCT 
Character Card Character Card Internal Character Internal 

Punch Punch Code Code 

R 11-9 R 11-9 51 R 122 

S 0-2 S 0-2 62 S 173 

t 0-3 + 0-3 63 i 124 

U 0-4 U 0-4 64 U 125 

V 0-5 V 0-5 65 V 126 

W 0-6 W 0-6 66 W 127 

X 0-7 X 0-7 67 X 130 

i § 0-8 ig 0-8 70 Y 131 

Z 0-9 Z 0-9 71 Z 132 

é 12-8-2(12-0) 2 2-8 LZ L 133 
0-8-2 _~ 12-7-8 S57 “XN 134 

| 12-8-7 ] 12-4-8 34 J 135 

pS 11-8-7 A 11-0 40 A 136 
0-8-5 < 0-2-8 72 137 
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Table D-2. Character Conversion Table (GBCD to ASCI1) 


em A err 


GBCD GBCD GBCD ASCII ASCII | BMEL I BMEL 
Character Card Internal Character’ Internal Character Card 
Punch Code Code Punch 
a cag snes senses gc apc inmate Ta 
0 0 00 0 060 0 0 
1 1 01 1 061 i 1 
2 2 02 2 062 2 2 
3 3 03 3 063 = 3 
4 4 04 4 064 4 4 
5 5 05 5 065 5 5 
6 6 06 6 066 6 6 
7 7 07 7 067 7 7 
8 8 10 8 070 8 8 
9 9 i BS 9 071 9 9 
E 2-8 12 io ¢ 12-8-2(12-0) 
# 3-8 13 # 043 # 8-3 
@ 4-8 14 @ 100 @ 8-4 
: 5-8 15 : 072 : 8-2 
> 6-8 16 > 076 > 0-8-6 
? 7-8 te is 077 ? 0-8-7 
blank blank 20 blank 040 blank blank 
A 12-1 21 A 101 A 12-1 
B 12-2 22 B 102 B 12-2 
C 12-3 23 § 103 C 12-3 
D 12-4 24 D 104 D 12-4 
E 12-5 25 E 105 E 12-5 
F 12-6 26 F 106 F 12-6 
G 12-7 27 G 107 G 12-7 
H 12-8 30 H 110 H 12-8 
| 12-9 BL | Lik | 12-9 
& IZ 52 & 046 & a2 
‘ 12-3-8 22 ; 056 - 12-8-3 
J 12-4-8 34 ] 135 | 12-8-/7 
( 12-5-8 55 ( 050 ( 12-8-5 
< 12-6-8 36 4 074 < 12-8-4 
\ 12-7-8 a7 \ 134 0-8-2 
A 11-0 40 A 136 = 11-8-7 
J 11-1 41 J Liz J 11-1 
K 11-2 42 K aH K 11-2 
L 11-3 43 a 114 b 11-3 
M L1i-4 44 M 5 M 11-4 
N 11-5 45 N 116 N 11-5 
¢) 11-6 46 0 riz 0 11-6 
P 11-7 47 P 120 P Lli-7 
Q 11-8 50 Q E22 Q Li-8 
R 11-9 aL R £22 R 11-9 
- Let Be - 055 - ie 
$ 11-3-8 53 $ O44 $ 11-8-3 
* 11-4-8 54 * 052 * 11-8-4 
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Table D-2 (cont). Character Conversion Table (GBCD to ASCI1) 


GBCD GBCD GBCD ASC ASCH 1 BMEL 1BMEL 
Character Card Internal Character Internal Character Card 
Punch Code Code Punch 
) 11-5-8 55 ) 051 ) 11-8-5 
: Lt=6=6 56 : 073 : 11-8-6 
: 11-7-8 57 . 047 y 8-5 
+ 12-0 60 ~ 053 + 12-8-6 
/ 0-1 61 J 057 / 0-1 
S 0-2 62 S Be S 0-2 
7 0-3 63 cf 124 T 0-3 
U 0-4 64 U L25 U 0-4 
V 0-5 65 V 126 V 0-5 
W 0-6 66 W 127 W 0-6 
X 0-7 67 X 130 X 0-7 
¥ 0-8 70 Y 31 b 6 0-8 
Z 0-9 71 rd 132 Z 0-9 
<- 0-2-8 72 = I ho » 0-8-5 
F 0-3-8 ri . 054 P 0-8-3 
z 0-4-8 74 % O45 % 0-8-4 
ce 0-5-8 75 = 075 = 8-6 
, 0-6-8 76 " 042 ' 8-7 
! 0-7-8 iF ! 041 ! 11-8-2(11-0) 
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Table D-3. Character Conversion Table (ASCII to GBCD and !BMEL) 


ee nL 


ASCII ASCII GBCD GBCD GBCD IBMEL | BMEL 
Character’ Internal Character Card Internal Character Card 
Code Punch Code Punch 
a a ne a aT ee eI I i eR ee ST a eT OT A ee RE EON ere ee nana e 
blank 040 blank blank 20 blank blank 
! O41 ! 0-7-8 77 ! 11-8-2(11-0) 
a 042 , 0-6-8 76 : §-7 
# 043 # 3-8 13 # 8-3 
$ O44 $ 11-3-8 53 $ 11-8-3 
% 045 %, 0-4-8 74 %, 0-8-4 
& O46 & 12 37 & 12 
; 047 ' 11-7-8 a7 ; 8-5 
( 050 ( 12-5-8 35 ( 12-8-5 
) 051 ) 11-5-8 55 ) 11-8-5 
* 052 * 11-4-8 54 * 11-8-4 
+ 055 + 12-0 60 + 12-8-6 
4 054 ; 0-3-8 73 ‘ 0-8-3 
- 055 - ja 52 - 7 | 
‘ 056 P 12-3-8 a> 4 12-8-3 
} 057 j 0-1 61 / 0-1 
0 060 0 0 00 0 0 
1 061 1 1 01 1, 1 
2 062 2 2 02 2 2 
5 063 3 3 03 3 5 
4 064 4 4 04 4 4 
5 065 5 5 05 5 5 
6 066 6 6 06 6 6 
7 067 7 7 07 Z 7 
8 070 8 8 10 8 8 
9 O71 9 9 ag 9 9 
: O72 : 5-8 LS : 8-2 
: O73 $ 11-6-8 56 “ 11=8-6 
< 074 4 12-6-8 36 “4 12-8-4 
= 075 = 0-5-8 75 = 8-6 
> 076 > 6-8 16 > 0-8-6 
? O77 : 7-8 Lf ? 0-8-7 
@ 100 @ 4-8 14 @ 8-4 
A LOX A 12-1 ZL A 12-1 
B 102 B 12-2 22 B 12-2 
C L035 C 12-53 23 C 12-3 
D 104 D 12-4 24 D 12-4 
E 105 E 12-5 25 E 12-5 
F 106 F 12-6 26 F 12-6 
G 107 G 12-7 27 G 12-7 
H 110 H 12-8 30 H 12-8 
| Tit | 12-9 51 | 12-9 
J 112 J 11-1 41 J 11-1 
K flee Be: K 11-2 42 K 11-2 
L 114 L 11-3 43 L 11-3 
M Lis M 11-4 4 y M 11-4 
N 116 N 11-5 45 N 11-5 
¢) 5 ¢) 11-6 46 6) 11-6 
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Table D-3 (cont). Character Conversion Table (ASCII to GBCD and IBMEL) 
ASCII ASCII GBCD GBCD GBCD IBMEL IBMEL 
Character Internal Character Card Internal Character Card 
Code Punch Code Punch 
P 120 P 11-7 47 P 11-7 
Q 123 Q 11-8 50 Q 11-8 
R ive R 11-9 51 R 11-9 
S 125 S 0-2 62 S 0-2 
T 124 tr 0-3 63 1. 0-3 
U 25 U 0-4 64 U 0-4 
V 126 V 0-6 66 V 0-6 
W 127 W 0-6 66 W 0-6 
X 130 X 0-7 67 X 0-7 
¥ 131 4 0-8 70 ¥ 0-8 
Z LZ Z 0-9 71 Zz 0-9 
q SB c 2-8 12 s 12-8-2(12-0) 
4 134 i 12-7-8 a7 0-8-2 
7 135 7] 12-4-8 34 | 12-8-7 
A 136 A 11-0 40 11-8-7 
be 137 <— 0-2-8 72 = 0-8-5 
: 140 * 11-4-8 54 * 11-8-4 
a 141 A 12-1 24 A 12-1 
b Lh? B 12-2 Ze B 12-2 
e 143 G 12-3 23 § 12-3 
d 144 D 12-4 24 D 12-4 
a eS E 12-5 25 E 12-5 
f 146 F 12-6 26 F 12-6 
g LT G 12-7 yg § G 12-7 
h 150 H 12-8 30 H 12-8 
i Lod | 12-9 51 | 12-9 
j 152 J 11-1 41 J 11-1 
k 155 K 11-2 42 K 11-2 
1 154 L 11-3 43 ‘ 11-3 
m 155 M 11-4 4 M 11-4 
n 156 N 11-5 45 N 11-5 
fe) 157 @) 11-6 46 @) 11-6 
p 160 P 11-7 47 P 11-7 
q 1G. Q 11-8 50 Q 11-8 
r 162 R 11-9 oe | R 11-9 
Ss 163 S 0-2 62 S 0-2 
£ 164 T 0-3 63 Bi 0-3 
u 165 U 0-4 6 4 U 0-4 
V 166 V 0-5 65 V 0-5 
Ww 167 W 0-6 66 W 0-6 
x 170 X 0-7 67 X 0-7 
y Lv Y 0-8 70 ¥ 0-8 
Z pe Z 0-9 rg Z 0-9 
4 175 ‘ 12-7-8 37 0-8-2 
174 I 0-7-8 77 ! 12-8-7 
» 175 \ 11-4-8 54 0-8-2 
a 176 X 11-4-8 54 0-8-2 
o 241 \ 11-4-8 54 0-8-2 
> 242 \ 11-4-8 54 0-8-2 
RY 243 \ 11-4-8 54 0-8-2 
4 244 Xi 11-4-8 54 0-8-2 
‘ 245 \ 11-4-8 54 0-8-2 
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APPENDIX E 


INTERNAL REPRESENTATION OF PL/I DATA TYPES 


This appendix gives the internal representation for each of the PL/I data 
types in both the UNALIGNED and ALIGNED cases. The data types are given by 
classification, as follows: 


Arithmetic 
String 
Address 
Area 


The boundary requirement and default alignment are summarized for each data type 
in the classification. Diagrams for the UNALIGNED and ALIGNED representation 
for each data type then follow. 


RITHMETIC DATA TYPES 


The arithmetic data types, their boundary requirements, and their default 
alignment are listed here: 


Boundary Required Default 

Data Type Prec, UNALIGNED LI GNED Alignment 
REAL FIXED BINARY single bit word ALIGNED 
double of th 3 even-word ALIGNED 
REAL FIXED DECIMAL byte word ALIGNED 
REAL FLOAT BINARY single bit word ALIGNED 
double bit even-word ALIGNED 
REAL FLOAT DECIMAL byte word ALIGNED 
COMPLEX FIXED BINARY single eS ae even-word ALIGNED 
double bit even-word ALIGNED 
COMPLEX FIXED DECIMAL byte word ALIGNED 
COMPLEX FLOAT BINARY single bit even-word ALIGNED 
double bit even-word ALIGNED 
COMPLEX FLOAT DECIMAL byte word ALIGNED 
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-Point Binar 


A real fixed-point binary number of precision (p,q) is stored as a_ two's 
complement binary number, n, as follows: 


SINGLE PRECISION O<p<36 


If ALIGNED, the number is positioned at a word boundary and occupies one 
word, as follows: 


If UNALIGNED within a structure, the number is positioned at a bit boundary 
and occupies p+l bits, as follows: 


DOUBLE PRECISION 35<p<72 


If ALIGNED, the number is positioned at an even-word boundary and occupies 
two words, as follows: 


1f UNALIGNED within a structure, the number is positioned at a bit boundary 
and occupies ptl bits, as follows: 
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The 


Fixed-Poi Decim 


A real fixed-point decimal number of precision p is stored as a_ string of 


p+t1l characters, as follows: 


if ALIGNED, the number’ is positioned at a word boundary and occupies an 
integral number of words; some trailing bytes may be unused. 


ae | ITIITILAT TI TAT TAT TATFE 


If UNALIGNED within a structure, the number is positioned at a byte 
boundary and occupies pt+l bytes, as follows: 


the sign, either '+' or '-', and the remaining 


left most character Is 
characters are from the set '0123456789'. 
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Real Floating-Point Binary 


A real floating-point binary number of precision (p,q) is stored as a two's 
complement binary fractional mantissa, m, and a two's complement binary integer 


exponent, e, as follows: 


SINGLE PRECISION 0<p<28 


If ALIGNED, the number is positioned at a word boundary and occupies one 
word, as follows: 


If UNALIGNED within a structure, the number is positioned at a bit boundary 
and occupies pt9 bits, as follows: 


D+k+8 


0 k k+8 


DOUBLE PRECISION 27<p<64 


If ALIGNED, the number is positioned at an even-word boundary and occupies 
two words, as follows: 


78 


If UNALIGNED within a structure, the number is positioned at a bit boundary 
and occupies pt+9 bits, as follows: 


0 p+k-28 35 


The value zero is represented as m=0 and e=-128. 
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i Real Floating-Point Decimal 


A real floating-point decimal number of precision p is stored as a signed 
decimal integer, m, and a 9-bit, two's complement binary integer exponent, as 
follows: 


If ALIGNED, the number’ jis positioned at a word boundary and occupies an 
integral number of words, as follows: 


LEST UPLTLTIG TEERL IT TEC ET 


If UNALIGNED within a structure, the number is' positioned at a byte 
boundary and occupies p+2 bytes, as follows: 
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Complex Fixed-Point Binary 


A complex fixed-point binary number is stored as a pair of two's complement 
binary integers. The first integer, r, is the real part of the complex value 
and the second integer, i, is the imaginary part of the complex value. 


SINGLE PRECISION 0<p<36 


If ALIGNED, the number is positioned on an even-word boundary and occupies 
two words, as follows: 


If UNALIGNED within a structure, the number is positioned at a bit boundary 
and occupies 2(ptl) bits, as follows: 


D+k 


0 KtZp=3> a5 
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DOUBLE PRECISION 35<p<72 


If ALIGNED, the number is positioned at an even-word boundary, and occupies 
four words, as follows: 


If UNALIGNED within a structure, the number is positioned at a bit boundary 
and occupies 2(ptl) bits, as follows: 


The ending bit position x has the value MOD(p+k+1, 36). 
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om Fixed-Poi im 


A complex fixed-point decimal number of precision p is stored as a pair of 
real fixed-point decimal integers of precision p. The first integer, r, is the 


real part of the complex value and the second integer, i, is the imaginary part 
of the complex value. 


if ALIGNED, the number is positioned at a word boundary and occupies an 
integral number of words, as follows: 


If UNALIGNED within a structure, the number is positioned at 


a byte 
boundary and occupies 2(pt+l1l) bytes, as follows: 
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Complex Floating-Point Binary 


A complex floating-point binary number is stored as a pair of binary 
floating-point numbers. The first floating-point number, r, is the real part of 
the complex value and the second floating-point number, i, is the imaginary part 
of the complex value. 


SINGLE PRECISION 0<p<28 


If ALIGNED, the number is positioned at an even-word boundary and occupies 
two words, as follows: 


If UNALIGNED within a structure, the number is positioned at a bit boundary 
and occupies 2(pt+9) bits, as follows: 


where x = MOD(k+2*p+17, 36). 


DOUBLE PRECISION 27<p<64 


If ALIGNED, the number is positioned at an even-word boundary and occupies 
four words, as follows: 


Ed DEO4 


If UNALIGNED within a structure, the number is positioned at a bit boundary 
and occupies 2(p+9) bits, as follows: 


where x = MOD(k+2*p+1/7, 36). 


Complex Floating-Point Decimal 


A complex floating-point decimal number of precision p is stored as a pair 
of real floating-point decimal numbers of precision p. The first number, r, is 
the real part of the complex value and the second number, i, is the imaginary 
part of the complex value. 


If ALIGNED, the number is positioned at a word boundary and occupies an 
integral number of words, as follows: 
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If UNALIGNED within a structure, the number jis’ positioned at a byte 
boundary and occupies 2(pt+2) bytes, as follows: 


STRING DATA TYPES 


The string data types, their boundary requirements, and their default 
alignment are listed here: 


Boundary Required Default 
Data Type UNALIGNED ALIGNED Alignment 
Bat bit word UNALIGNED 
CHARACTER byte word UNALIGNED 
PICTURE byte word UNALIGNED 
BIT VARYING word word ALIGNED 
CHARACTER VARYING word word ALIGNED 


Bit-String 
A bit-string of length n is stored as n consecutive bits. 


[f ALIGNED, the bit-string is positioned at a word boundary and occupies an 
integral number of words, as follows: 


If UNALIGNED within a-— structure, the bit-string is positioned at a bit 
boundary and occupies n bits, as follows: 


0 k k+n-1 35 
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Character-String 


A character-string of length n is stored as n consecutive bytes. Each byte 
contains a single 7-bit ASCII character right-justified within the byte. The 
two unused bits must be zero. WW 


If ALIGNED, the character-string is positioned at a word boundary and 
occupies an integral number of words, as follows: 


Q 3 18 7a | 35 
Seg PMI 


If UNALIGNED within a structure, the character-string is positioned at a 
byte boundary and occupies n bytes, as follows: 


0 9 18 ram 


PICTURED CHARACTER-STRING 


A pictured character-string is represented as a character string of length 
n, where n is the number of picture characters excluding the characters V and K 
and the scale factor indicator F(Ci). For example, the picture "999V9" jis 
represented by a character string of length 4. 


If ALIGNED, the pictured character-string is positioned at a word boundary 
and occupies an integral number of words. 


If UNALIGNED within a structure, the pictured character-string is 
positioned at a byte boundary and occupies n bytes. 
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rying Bit-Stri 


The representation of a varying bit-string in storage is independent of its 
om alignment. A varying bit-string of maximum length n is stored as an ALIGNED 


binary integer followed by an ALIGNED bit-string. The binary integer contains 
the current number of bits, m, as follows: 


Varyi har r=Strin 


The representation of a varying character-string in storage is independent 
of its alignment. A varying character-string of maximum length n is represented 
by an ALIGNED binary integer followed by an ALIGNED non-varying character-string 


of length on. The binary integer contains the current number of characters in 
the string, as follows: 


exe aus peg fnmniat 
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ADDRESS DATA TYPES 


The address data types, their boundary requirements, and default alignments 
are given below: 


Boundary Required Default 
Data Type UNALIGNED ALIGNED Alignment 
LABEL word word ALIGNED 
ENTRY word word ALIGNED 
FORMAT word word ALIGNED 
POINTER bit word ALIGNED 
OFFSET bit word ALIGNED 
FILE word word ALIGNED 


Label, Entry, And Format 


The label, entry, and format data type have the same internal 
representation. Each contains a pointer, pl, to a statement within a procedure 
and a pointer, p2, that identifies the stack frame for the most’ recent 
activation of the block immediately containing the statement located by pl. The 
UNALIGNED and ALIGNED representations are the same, namely: 


A pointer consists of a word address and bit offset from the start of that 


If ALIGNED, a pointer begins at a word boundary and occupies one word, = as 
follows: 


<---b--->1000000000000000 


If UNALIGNED within a structure, a pointer is positioned at a bit boundary 


and occupies 36 bits. 
The null pattern for a pointer is: 


18 


11111111111111111110000000000 


24 S 


000000000000000 
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Offset 


An offset contains a word offset, w, from the start of an area, and a bit 
offset, b, from the start of the word. 


If UNALIGNED within a structure, an offset is positioned at a bit boundary 
and occupies 36 bits. If ALIGNED, an offset begins at a word boundary and 
Occupies one word, as follows: 


18 


24 5 


000000000000000 


The UNALIGNED and ALIGNED representations for a file data type are the 
same. The representation consists of a full word whose upper half is a pointer, 
pl, to the file-state block, as follows: 


0 18 22 


a ta Se elo ng had Sep al >00000000000000000 


AREA DATA TYPE 


An area data type of size k is positioned at an even-word boundary and 
occupies k words. 


An area is divided into a series of contiguous blocks by the allocation of 
based variables. The first block is the occupation record. The occupation 
record has the following format: 


0 18 oe. 
as Seem 
ee Serena 


000000000000000000 


22 words 


where A is the length of the occupation record. 

B is the offset of the last word of the area. 

C is the offset of the next available block space minus l. 

D is the size of the next contiguous block, if one has been allocated. 

X is the busy indicator for the next contiguous block. 
ity ”~A = as the next Block Ss currently al located. 

E is the word offset from the beginning of the area of the next contiguous 
block 

Y is the busy indicator for the current block. 
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The remaining words of the occupation record are used in the management of 
block space made available when based variables are freed in the area. 


Before any based variables are allocated, the area is zero, except for C in 
the occupation record, which has the value k. When a based variable is 
allocated, a block is created in the area. In this way, blocks are allocated 
starting from the end of the occupation record and proceeding from low to high 
addresses until the end of the area is reached. Each block begins on an even 
word boundary and occupies an even number of words. If the based variable 
requires n words, where nis odd, the block consists of ntl words. If nis 
even, the block consists of n+2 words. The last word of the block is called the 
block trailer word. The format of the block trailer word is illustrated in the 
diagram of the occupation record. 


The number of words available for allocation in an area can be calculated, 
as follows: 


S Before any based variables are allocated in an area of size k, _ the 
amount of block space s is given, by the following formula: 


s = k - 22 - MODCKk, 2) 
where MOD is the PL/I built-in function. 
e After an initial sequence of n based variables has been allocated and 


none freed, the remaining available block space rs is given by the 
following formula: 


rs. =<S = >, (m, + 1 + MOD(m, +1, 2)) 


where m, is the number of words required by the ith based variable. 
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APPENDIX F 


EXTERNAL NAMES 


This appendix describes the conversion rule applied to external names and 
lists the external names reserved by the system. 


CONVERSION RULE 


Although in PL/I no restriction on the length of external names is imposed, 
the Loader restricts the length of external names to six or less characters. 
Also, the characters '$' and '_' cannot be part of the external name. 


To convert a PL/I! external name to an acceptable external name for_ the 
General Loader, the following rules are applied: 


1; The characters '$' and '_' are converted to the character '.'. For 


example, '$A$B_C' becomes '.A.B.C'. 


ae if the external name contains more than six characters, it is 
converted to a six character name by concatenating three strings, as 
follows: 


Sit] sZtt s3 


where: sl is the number of characters in the name mod 10. If the 
number of characters mod 10 is zero, then sl = Mies 


s2 is the first character of the name. 
s3 is composed of the last four characters of the name. 


For example, consider the following external names and their converted 
names: — 


External Name fe) rted E r Nam 
ABCDEFG 7ADEFG 
ABCDEFG_HI .AG.HI 
H25MODEL1 Q9HDEL1 
H26MODEL1 9HDEL1 
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Note that the last two different external names are converted to the same six 
character name for the Loader. In order to be unique, names of the same length 
must differ in either the first character or one of the last four characters. 
Similarly, names that are distinguished from each other only by the characters 
'$" and '_' are converted to the same external name, as follows: 


External Name ; Converted External Name 
$ABC ~ABC 

_ ABC ~ ABC 

H25MODEL$ QHDEL. 

H26MODEL_ QHDEL. 


In addition to being distinct from one another, external names must be 
unique with respect to reserved system names. A list of the external names 
reserved by the system is given in the next section of this appendix. To assure 
uniqueness, an external name must be converted and compared against the list of 
system reserved names. For example, the external name 'LONGLENGTH' cannot be 
used because it is converted to the name '.LNGTH', which appears on the list of 
reserved names. 


RESERVED EXTERNAL NAMES 


Table F-1 lists the external names that are reserved by the system. This 
list may change slightly depending on the update level of future software 
releases. It is primarily composed of entry names to execution-time support 
modules in the PL/I library fille. <A current list of that file, and other 
libraries, may be generated by use of the cross reference service program .SREF. 
For instructions on use of that program, see the Service Routines manual. 


Table F-1. Reserved External Names 


ea now ree as ew Ne aa Des ooeW.. 
- eABOR eeABT ~- ABTI »-ALOC »- ANDI 
sell «- CMB1 se CMC2 - « CONV .--COPN 
ce bREA .- CRWT -- CWRT oe BARL + «G80 

«<8DB, ~ [ABT sel Gls ~eIDEE ws TOPN 
~- IREA ee T RVT oe IRWT oe IWRT .- LOOK 
ae MBL oeMCl1 --MNI ssORL . » RABT 
«eRALC ~«RBAC JeneLe , oe KEENE .eROPN 
»»RREA oe RRVT »»RRWT - eRWRT -- SBA 

oe SCA ¢esF CB j20EEF seorur ees! 

er A as eS oF abe Al ~A2 -A3 

~ ALLA ~ALLCA »ALLOC ~BCS1 ~BI TOP 
» BLANK « BMUU «BOP -CALSG CAT 

« CMUU . COMI O - COUNT sDBLEP ~DESCI 
LY. « EMCP sERPC. ~ ESW » EXCG. 
sEXTSZ ePREE ~GETAQ ~GLGE « ENETET 
» POFLG bO0d »LOO2. eEOUS:.s eiGos:. 
ebOOT. Pa Se Te « LO3S-. oLO80. ~LO41. 
@hUGZ. ~LO43. «LOeS, ~LO46. «LORF. 
~LO48. «LOSS, ~ L050. ag Ns ~LOSZ:, 
Py es eee ~LO54. LOSS; + bO56.. «LOSS. 
okOSS: GhOGEs $EU0S. eLOSSs «LOGS. 
(1067, eLUGB. LOGS. Pa te ge me aa 
LOUIS. » LO7E. me Ra ase FLUTE « L080. 
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~ L082. 
~LOGZ« 
~MVRET 
~OHAR. 
~ONES 

~P.REW 
- P0003 
. P0008 
. P0014 
~ P0019 
~ P0024 
- P0034 
- P0039 
-POO44 
- P0049 
~ P0054 
. P0061 
. P0066 
~ P0071 
. P0076 
~P0081 
. P0086 
«POUGSL 
«P0097 
. P0102 
<POLO7 
sPODLE 
<eOLLF 
ePOL2Z2 
PULZ7 
+ P0132 
POLST 
2POLN2 
~ P0147 
ePOCLS2 
-PEISS 
«P0163 
«POLS 
» POLS 
-P0178 
ePULS3S 
- P0188 
sPG193 
sPOL9S 
~ P0203 
. P0208 
~ P0213 
«P0218 
P0223 
~ P0228 
<POZ253 
«P0258 
~PO2ZH3 
~ P0248 
sPGZ53 
eF 299 
- P0264 
<PO2ZES9 
~P0274 
P0280 


Table F-1 (cont). 
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Reserved External Names 
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«P0285 
«P0280 
«PUZ95 
. P0300 
ePUSeS 
sPUSLO 
aPODL9 
~P0324 
grtses 
~P0334 
P0329 
~PO344 
«P0349 
~ P0354 
. P0360 
~P0365 
srO0az7D 
cPUor> 
- P0380 
«PUSS5 
«P0590 
~POLO1 
~ P0409 
~ P0423 
~ PADIT 
PUTAS 
sPrLOr 
+ PLOO? 
ePCUTZ 
ePEUAs 
sPLUZZ 
-reoe? 
sree 
«PLOS7/ 
»PLO42 
»~PNIB, 
» PR8EC 
» PUND. 
~RBUF1 
»RDCPY 
~RECIO 
~RPDPT 
~SGJIN 
SSTKIL 
eSX2Z9 

» TEMP2 
~TSX45 
1CCOS. 
1GCARD 
1PEAD. 
SPrene 
2AIND. 
2CBIT. 
2D0G2. 
2ORCE. 
2POSE. 
3BI1TH. 
3DORT. 
SPATE. 
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P0286 
~ P0291 
» P0296 
<POSOT 
. P0306 
ePGS15 
~ P0320 
oPO325 
«P0350 
9 Be be 
~ P0340 
~P0345 
sPUSSO 
sPYooe 
~ P0361 
- P0366 
ePOS TL 
«P0376 
&PESE1 
~P0386 
~PCS91 
~PO402 
~ P0410 
~PO424 
» PAGES 
» PDESC 
-PLOOL 
. PL008 
sruuso 
SPLULS 
+PCOZS 
cP LuZe 
sPLES3 
-PL038 
«PLOGS 
<PRle. 
.» PROPN 
» PWRPU 
«» RBUF 2 
» RDMOV 
~REM1 
Rr 
~oIND., 
«STORE 
~SX45 
« TMRAQ 
~XR2 
ICTAN. 
LTLANH. 
1PG2EE 
ISECK. 
2A0SD. 
2CINH. 
2DONE. 
2PFSBP 
2PR30S 
3CCOS. 
3DTAN. 
SFECES 


~ P0287 
«P0292 
sFPoLy7 
~ P0302 
srusuy 
se USLs 
<PuSL. 
«P0326 
¢PUSS1 
-ro556 
sr uses 
~P0346 
<POUSS] 
+ PU357 
~P0362 
a ed | 
eeOstaZ 
«PO377 
¢PUsS2 
» P0387 
oPUSo2 
. P0403 
~PO417 
~PO425 
. PASCB 
.PeMrs 
»PLOO4 
<PLUUS 
~PLO14 
LPLULS 
~PLO24 
» PLO29 
»PLO34 
sPLOS59 
ePLABY 
~PNTN. 
.PROR. 
ePZDTV 
~RCLSE 
»RDOPR 
~REM2 

soo T TP 
.90SD. 
eSTERI 

~ 3X67 

- IMPBP 
1ACOS. 
1D.OP. 
ILGIG. 
1PLATE 
1SOSH. 
2ATAN. 
2COSH. 
2DOSD. 
Z2PLTE. 
2 PREAD 
3DANH. 
SFIDE. 
3PP1DA 
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~ P0288 
seUza5 
«POZS8 
eFUS0S 
~P0308 
~P0317 
sFUSZ2 
~euoje?! 
iPOIe 
sUuoST 
sPUSE2Z 
~ P0347 
se Gsoz 
ErusDe 
. P0363 
-P0368 
ePOU375 
.P0378 
«P0383 
- P0388 
- P0393 
~P0407 
~P0418 
-P0426 
. PBACK 
aries 
.PLO05 
. PL010 
ePLOLS 
eT Rue 
ePLUZS 
sr L050 
oP bAroo 
- PLO4O 
+P LMES 
» PNTRM 
» PRPUT 
~ QMASK 
-» RDAND 
~RDOR 

eRGET 

esCILy 
~SREGS 
sorK2 

~ TAND. 
~» TMPPT 
LAEDEF 
1DCOS. 
10.TOP 
1PNAL. 
2AAND. 
2BHAR. 
2DAND. 
2DRFC. 
LPEAUs 
3ABIT. 
3DG10. 
30NKEY 
3PR301 


«POQ2E9 
~P0294 
«POZS9 
~P0304 
iPESUS 
~ P0318 
sPOs2> 
sPUses 
sPUus>S 
sPOUS58 
~ P0543 
~P0348 
PM ag |e ps 
~ P0553 
-P0364 
sPUS5o 
~ P0374 
<FUST9 
~P0384 
~P0389 
- P0400 
.P0408 
~ P0419 
~ P0428 
-PBCDA 
«PERL 

. PLOO6 
ePLGI4 
«PLOIG6 
sPLOZE 
~PLO26 
oPLOSE 
.PL036 
~PLO4I1 
. PMEMF 
POV L 
» PSETU 
»RABT 

~RDCP2 
~RDXOR 
~ROPEN 
~oETU. 
» STKHD 
~SX01 

21 EM 

~» IMPSZ 
LATAN. 
IFREE, 
1OURCE 
1PNTRY 
Z2AIGN. 
2CANH. 
2DIND. 
201 NFO 
2PNPUT 
3AQOSH. 
3DOSH. 
30NLOC 
3PR4CS 
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3PR5RI 
LAND2. 
4COSH. 
LOCODE 
4PNTER 
4PR4&CI 
5AITH. 
A ga a I 
5PR6WR 
6DINGS 
6OURCE 
6 PHAR. 
6 PUND. 
7DAN2. 
7ERFC. 
7PHAR. 
EP Se back 
FOLER. 
8EEXEC 
8 PHASE 
8SENCE 
SP 
9OCODE 
SPIME. 
9SCOS. 
ALLOC. 
CABS. 
CFMP 
CXP2. 
DCFMP. 
DERF 
DND 
DTANH. 
EXPON. 
LOG. 
PLINK 
RGET 
SNAP. 
TANH. 
ZASCGE 
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3PROR. 
4 BLOAD 
4DANH. 
4DFILE 
4 PONV. 
4 PR5RR 
5DCOS. 
SPEAR s 
ars Ll 
6DINH. 
6PALL. 
G6PPISS 
6RGGER 
7DINH. 
7CIELD 
7PNENO 
TPS aR 
7SNAL. 
8ONKEY 
8 PNAME 
8SRINT 
9GDATE 
SONDEX 
SPRaks 
O9SINT# 
AREA. 
CASIN. 
CLOG. 
DASTN. 
DCLOG. 
VEAR, 
DSIN. 
DXP1l. 
FREE. 
LSTKBT 
PLLINK 
ROPEN 
SORT. 
APL 
ZGEASC 


3SADDR 
4CANH. 
WDINH. 
LOTTOM 
4 PP1DD 
4 PR6WI 
5DOSH. 
DPLEXRs 
5PRIDI 
6DND2. 
6 PDESC 
6PR7LR 
6SE.NO 
#DORT. 
7PDLER 
7PR30C 
7SALUE 
7UHECK 
8ONLOC 
8PR4CC 
8SRMAT 
9GTIME 
Q9PATE. 
9PR7LC 
OTS 42. 
ASIN. 
CATAN. 
CSIN. 
DCABS. 
DCSIN. 
DT EAP 
DSINH. 
DXP 2% 
FREEN. 
PACKER 
PUP 
RPUT 
SYSIN 
AFD 
ZWATCH 


Reserved External 


So TOR, 
KCINH. 
4DOSH. 
4 PG1DD 
4 PP1DO 
4 PRACE 
SF ae its 
5PONV. 
SPSEt, 
6DOSH. 
Sr 3 
6PR8EI 
6SMBOL 
7DSIN. 
TPEDIT 
7PR5RC 
7SGNAL 
8C.OP. 
8PENO. 
8 PR6WC 
8UCKER 
Q9MDESC 
9 PDUMP 
9PRIDC 
= ae 
ASINH. 
CEAPs 

CSQRT. 
DCEXP. 
DGAP Ls 
DLOG. 

DSQRT. 
ERE. 

LEAP, 

PENTRY 
PUSH. 

SIN. 

SYSIN# 
ZAGPRT 
ZWTEND 


4AHAR. 
GCITH. 
4DTAN. 
GPEVLES 
4PR30OR 
5AAGE. 
Bg 
5PR4CR 
6DANH. 
6 1URCE 
6PG1SS 
6 PRI9DR 
6SRESS 
7DTAN. 
7PGENO 
7PR8ER 
7STON. 
8DRFC. 
SPEXT. 
8PURE. 
Q9BABLE 
9OCHAR 
9PGNAL 
Q9PSTAT 
ADEXP. 
ATAN2. 
CFOP. 

CXPl. 

DCFDP. 
DEXP2. 
DMOD. 

DTAN. 

EXP. 

LBSWRK 
PIDLNK 
RCLOSE 
S!NH. 

TAN. 

ZASCEL 
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APPENDIX G 


STRUCTURE OF THE INCLUDE FILE 


This appendix describes the structure of the INCLUDE file. Five figures 
are included. The first figure illustrates the general structure of the INCLUDE 
file; and the remaining figures illustrate the detailed structure of the 
components. 


INCLUDE FILE 


The INCLUDE file is structured as a random ASCII! file divided into 320 word 
blocks. The file consists of catalog blocks and data _ blocks. The catalog 
blocks are linked together. Following each catalog block are the data blocks 
that contain the macro text for the macro names in the catalog block. The 
format of the catalog and data blocks are given later in this section. The 
general structure of the INCLUDE file is illustrated in Figure G-l. 
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catalog 320 words 


data 320 words 


320 words 


data 320 words 


aol 


Figure G-l. Structure of the INCLUDE File. 
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Catalog Blocks 


A catalog block of an INCLUDE file contains a header, control information, 
and up to 15 macro identifiers. 


control 


macro-identifier-1l 


macro-identifier-2 


macro-identifier-14 


macro-identifier-15 


Figure G-2. Structure of a Catalog Block 


The header contains the ASCII string '"*SRCLIB*", 


The ‘control portton contains statistics about the macros in the file. The 
contents of the control portion are described in detail in the next section of 
this appendix. 


The macro-identifier contains the text-name associated with the macro and a 
pointer to the text. A detailed description of the macro-identifier is given 
later in this appendix. 
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CONTROL PORTION OF THE CATALOG 


The control portion of the catalog linkage and summary information is as 


follows. 


where: 


NE 
NDE 
LGB 
FGB 
NAVB 


NVB 


PC 
NC 


oe 
Oo 
m 


LGB FGB 


NAVB NVB 


“ey 
oO 
i 
>) 


MMMM 
MMMM 


MMMM 
LLL 


is the 
is the 
is the 
is the 
is the 


is the 
within 


is the 


is the 


number of macros registered. 

number of macros deleted. 

relative block address of the last macro deleted. 
relative block address of the first macro deleted. 
number of entries available in the catalog. 


relative block address of the first unused entry 
this catalog. 


relative block address of the preceding catalog. 


relative block address of the next catalog. 
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MACRO-IDENTIFIERS 


Each macro-identifier in the catalog portion contains the ASCII characters 
of the text-name associated with the macro and pointers to the text, as follows. 


where: 


NB 


NR 


text-name 


are the ASCII characters of the text-name associated with the 
macro. The fame can consist of up to 32 characters ClerTt 
justified, space filled). 


is. the relative block address -of -the. last «data block 
containing text associated with this text-name. 


is the relative block address of the first data block 
containing text associated with this text-name. 


is the deletion indicator. 


is the number of blocks occupied by the text associated with 
this text-name. 


is the number of records required for the representation of 
the text associated with this text-name. 
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Data Blocks 


fixed- 
data-records and can occupy more than one data block. 


block 


A data block contains two words of identification, followed by a series of 
data-records. The text for a macro occupies one or 


length 


is given here. 


20 words 


20 words 


20 words 


18 words 


where: 


BSN 
NBA 


FRN 


LRN 


aaa ge 


ae 
[_deterrecord-? 


data-record-15 
| morusee 


more 


The structure of the data 


is the logical serial number of the block in this macro text. 


is the relative block address of the next data block. 


is the serial number of the first data-record of the 
relative to this macro. 


is the serial number of the last data-record of the 
relative to this macro. 


block 


block 
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APPENDIX H 


GCOS PL/I COMPILER ERROR MESSAGES 


This appendix contains the error messages that can be produced by the GCOS 
PL/I compiler in the compilation of a source program. When the compiler detects 
an error, it writes the error message, as it appears in this appendix, on the 
error message listing. The action then taken by the compiler depends upon the 
severity of the error, as follows: 


Severity Action 

WARNING The program compilation continues. 

SEVERITY 2 The error is corrected and the compilation 
continues. 

SEVERITY 3 The compilation continues from the next logical 
starting point, but code generation is suspended. 

FATAL The compilation is terminated. 

f \ The symbol '‘'$' in the error messages listed here is replaced by an 


identifying name when the PL/I compiler detects an error and prints a message. 
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APPENDIX | 


ON-CODES 


| This section contains the meaning of the ON-code numbers printed as a 
| result of the detection of an error at execution time. 


The ON-code meanings are listed in the order of the associated number. For 
each ON-code number, the condition name and the meaning are given. 
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*3 h-7, block 14-3. 
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BUFSIZ option T= Ls 
access 6-1. 

by-value arguments 15-17% 
address calculation 14-6. 

Cx 4-6, 
ALIGNED 11-1. 

catalog block G-3. 
aligned attribute 11-1. 

changing do-group index 15-8. 
alignment 1h-3, 14-12. 


default 11-2. character 
combination 15-2, 
allocation confusion L5=2% 
variables 15-10. picture 15=3.% 


special 15-2. 

ALTER control card 12=3 3 

CHARSZ option F fea 
Alter file b=-6, 

CHECK option h-10, 
alter listing h-18, 

coarse index 8-4, 
ALTNO option h-10, 

CODE GENERATION heh, 


argument 
external procedure 13-10. COMDK option h-10. 
internal procedure L5=11, 
parenthesized 15-18. COMMON phase iS 
argument by-value thos os Se compiler 
code generation phase bh. 
argument descriptor 10-4. control phase ee oe 
error message editing beh, 
argument list 10-3. files heh, 
optimization phase k= 3, 
argument type 10-4. option listing h-19, 
options Ey ae 
ASCI1 option } ae a output 
alter listing 4-18. 
attribute INITIAL L>e32, compiling statistics we2h, 
cross reference table 4-20. 
Bx 4-6, error message be2h, 
expanded source 4-19, 
BASED variable t5=12, external symbol listing h-21,. 
object program b-23, 
BCD devices 15-21. object program map 4-22, 
option listing h-19. 
BCD option elo yr storage capacity 4h-25. 


storage space u-21. 
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output PRINT 6-9. 
symbol table 4-20. PRMFL G= 7-5 
output listing 13=15; PUNCH b=, 
phases hel, READ 6-8. 
semantic analysis phase 4-3, SAVE 12-5. 
Syntax analysis phase ke-3, SNUMB oe 
Special option 
compiler output listing he-17. COPY 4h-16. 
OPTIONS h-17. 
compiling statistics listing 4-2, SUBTITLE h-16., 
| TVILE 4-16. 
compressed deck file h-6. SRCLIB LJ=Z, 
SYSOUT 6-8. 
concatenation 14-11. TAPE — 6-7. 
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conflict name 15-4. TAPES 6-7. 
USE 5-10. 


confusion 
character L5=2. control format items 15=20:. 
operators 15-2. 
control option 15-20. 
CONGO option 5-9. 
conversion 15-16. 


CONSECUTIVE file data lh-2. 
attachment 7-1, 7k. errors 15<15.. 
control cards 733 loss of precision 15-16. 
descriptor file 7-3. scale-factor 1h-5, 
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COPY control card 1255 
CONSECUTIVE organization 7nm1. 
COPYRIGHT control card 4-16. 
CONSECUTIVE RECORD 
access 7-9. CREATE control card 12-4. 
creation 7-8. 
CSP DATA card 123; 
CONSECUTIVE STREAM 
access 7-6. CSYM option 1 eat 1 
creation 7-5. 
D« 4-6, 
constant arguments Lhu-11. 
DAC control card 7-10. 
control card 


ALTER 12-3. DATA Card 
CONSECUTIVE file T3536 CONSECUTIVE file TPD% 
COPY 12-3. INDEXED file 8-10. 
CREATE 12-4. REGIONAL file 9-6. 
DAC 7-10. 
DATA 3-2. DATA control card 3-2. 
DELETE 12-4. 
device assignment 6-6. data conversion Lh-2,. 
ENDJOB 2-3. 
EXECUTE 2-2. data file 8-h, 
FILE 6-6. size calculation 8-12, 8-15. 
| DENT 2-2. structure 8-4, 
INDEXED file 8-9. 
INITIAL 12-4. data types 14-1. 
LIMITS 2-2. 
LEST 12-5. data-directed input-output 14-14. 
loader 5-5. 
DKEND -6. debugging i Ge 
ENTRY 5-6. 
LIBRARY 5-7. debugging constructs 1h-2. 
LINK 5-7. 
MODIFY 12-5. DECK option he10, 
OBJECT 5-8. 
OPTION 2-2, 5-8. default alignment Li-2. 
PL1 2-2. 
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DELETE control card 12-4, 

descriptor 
argument 10-4. 

descriptor file 
CONSECUTIVE 
INDEXED 8-9. 
REGIONAL 9-6. 


FAs 


device assignment control cards 


5-6. 


device requirements 6-9. 


DIAGNOSTIC beh, 
direct access 
INDEXED 8-2, 
REGIONAL 9-2, 
5-6. 


DKEND control card 


dummy record 9-1, 


DUMP option 5-6. 


edit-directed input-output 
efficiency 
choice of data type 
rules a ace! 


efficient programs LT 


ENDJOB control card 2-3. 


ENTRY control card 5-6. 
entry points 
multiple 15-19. 


ENTRY variable 15-9, 
equivalent storage 
COBOL 10-1. 
COBOL-74 10-2. 
FORTRAN 10=2. 
ERCNT option 5-9. 
error message 
fatal h-12, 
warning h-12, 


error message listing 
13-3. 


error trace-back 
example ABZ « 


errors 
conversion 
evaluation 15-13. 
examples 15-1. 
initialization 
input-output 
procedure calls 
program constructs 


LOM LS 


Lots 
Lome, 
te aw a ge 
Lok 


ae 


4-24, 


Lh-12. 


errors (cont) 
program control 
program structure 


£5274 
L548, 


evaluation 
errors 15-13. 
increments 15-11. 
limits 15-11. 


evaluation order 
assignment 15=13. 
expressions 15-14. 

EXECUTE control card 2= 25 


execution report 


1351. 13593: 


expanded source program listing 


f<-19;, 


external variables 14-14, 


fatal error be-12,. 


PRUE Contre (oeard BF. 

file 
access 
alter EG. 
compiler ml, 
compressed deck 
data 8-h, 
INCLUDE 12-1, 
index 8-k, 
object deck 126: 
object program R= 6:4 
Organization 6=24 
record G=3. 
secondary system standard 

rls 

source program 
SRCLIB input 
SRCLIB work 
stranger option 
system input aaa | 
system output 
work m7. 


Gedy 


4-6, 


| ow ae 


4-7, 
Ie a oe 
Uae a 
4-6, 


file access 
CONSECUTIVE RECORD 
direct S=2;5 G22 
INDEXED Su iy BLL 
REGIONAL 9-7, 9=11. 
sequential Sql, Sez. 


| fea 


file attachment 
CONSECUTIVE 7- 
INDEXED 8-9, 8 
INTERACTIVE 7- 
REGIONAL 9-6, 


file code 6-4, 


FILE control card 6-6. 
file generation 
CONSECUTIVE RECORD 


CONSECUTIVE STREAM 


library 
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file generation (cont) INDEXED file 


INCLUDE file 12-6. access 8-1, 8-21. 
INDEXED - 8-1. attachment 8-9, 8-14. 
INDEXED file 8-19. control cards 15-21, 8-9. 
REGIONAL 9-1, 9-10. creation 8-1, 8-19. 
descriptor file $-S. 
file organization Lh-1u,. memory reservation 8-11. 
size calculation oll a 
file size structure 8-h, 
data file 8-12. transmission statements 8-2. 
index file 8-13. utilization report 8-16. 
INDEXED file 8-12. 
REGIONAL file ! coe ae INDEXED organization 8-1. 
file structure INITIAL attribute 15=12. 
data 8-4, 
INCLUDE file G-l. INITIAL control card 12-4. 


index 8-7. 
INDEXED 8-4 
REGIONAL 9- 


F initialization 14-11. 
4. errors Lod. 
variable 15-10. 

filler storage 113% 

input strings 15-20. 
fine index 8-h, 

input-output 
FIXED record 6-4, errors 15-19. 

lists 15-20. 

fixed-point 


addition 14-5. input-output interface 14-15. 
division Lh=4, 5-55. 
multiplication 14-4, INTERACTIVE file 
subtraction 14-5. attachment 7-9. 
FIXLNG option 7-2. INTERACTIVE option 7-3. 
FLOATBIN option beh, INTERACTIVE organization 7-9. 
funtion reference 15-18. invariant computations 14-8, 
global variable references 14-10. ISP DATA card 8-10. 
GO option 5-9. ISP INDEX card 8-9, 
| * 3-1. ISP RECORD card 8-10. 
|IBMFORM option be15, K* kG. 
IDENT control card 2-2. key offset 


calculation 8-15. 
identifiers 
restriction 15-4. key size 2 ease tel 
calculation Se 15% 


IN 1 i ae 
& 5-2. 
INCLUDE file iZnw 1s. he Ff, 
creation 12-6. LABEL variable 15-9. 
modification 12-7. 
saving 12-7. labels thet? 
structure G-l. 
use 12-8. layout 
member arrays 11-10. 
INDEX card member scalar 1li-4. 
INDEXED file S=9, member structure Li-7. 
rules Ll. 
index file 8-4, structure 14-8. 
size calculation 8-13, 8-16. 
structure §-/., LEAVE option Jr 3% 


i-4 DEO4 


LIBRARY control card 5-7. 


LIMITS control card 2-2. 


line size 15-21. 


LINESIZE option aaa are 


LINK control card 5-7, 


LIST control card 12-5. 


LiST Option h-10,. 
listing 
compiler output 135-15, 
loader map £3621. 


loader 
functions 5-1. 
5-5. 


loader control cards 


loader map 13-21, 
13-4, 
13-10, 
13-30. 
13-7, 
13-28. 
procedure 
static 
procedure 
Static 
13-6. 
[5-h., 


locating 
arguments 
example 
automatic 
example 
external 
external 
internal 
internal 

label 
variables 


i aa 


| ae 
13* 3% 

Lori 
L3"6% 


LOCK option 173 


logical expressions lh-7, 


LONGFORM option be15, 


LSTIN option 4h-11, 


LSTOU option Te 


LUD 6<6, 


major variable 
positioning LimZ% 


major variables 11-1. 


MAP option bell, 5-9, 
member array 
layout 11-10. 


member scalar 
layout 11-4. 


member structure 
layout 11-7. 


member variable 


positioning 5 


2= 1.0, 


pelt. 


member variables 11-1, 
layout LL=4. 
memory diagram 
overlay te 
memory layout L3=ty 
example 13-27% 
memory reservation 
calculation S155 
minimum storage Lio 
minimum unit LILA 
mixed transmission Ler Zils 
MODBCD option L725 
MODIFY control card L2* 53 
MODMIX option a ae 
multiple entry points 
name 
external boli, 
NBUFFS option Sea 0" 
NDUMP option oa OE 
NOGO option see 
NOMAP option 5-3. 
NOMSUB option S=9 
NOPAC option lt ee ae 
NOSREF option a9, 
NSTDLB option TH24 
NTAB option T= 3% 
OBJECT control card 5=8:, 
object deck file b=6. 
object program file b-6, 
object program listing 
object program map a as ae 
OLEAVE option FA 3% 
ON unit Loa 3< 
ON units Lh 3. 
ONCODE Lon 3 
option 
ASCII (ea BS 
BCD i-3 


1S=19 


4-23. 


option (cont) OPTZ phase a 
BUFSIZ 7-2. 


CHARSZ oe Organization 
compiler he-7, CONSECUTIVE 7*1, 
ALTN 4-10. INDEXED S-1, 
CHECK 4-10. INTERACTIVE 773, 
COMDK b-10, REGIONAL 9-1. 
CSYM 4h-10. 
DECK he10,. overflow pages S74 
FLOATBIN h-14, 
| BMFORM h-15, overlay diagram 5-13. 
LS t 4-10. 
LONGFORM he15, overlay segment 5-10. 
LSTIN h-11, 
LS TOU he-1l,. Overlay segment loading tae Oe 
MAP hell, 
OPTZ he-1il. Overlay structure 5-10. 
PARSE h-1l1., 
SEC_SYMDEF = 15% overlay tree at ON 
SEVER DY oe i 
SHORT_CALL he15, Px S*L,. BeT. 
SMESSAGE h-15, 
SNUMBER 4-12. packed 10-4, 11-4. 
special 4h-13, 
special control 4-16. packed property li-4. 
STAB h-12. 
Standard control cards ie ee packing status 10-4. 
STATUS 4-16. 
SYMT he-12. page 8-4, 
XREF h-12, 
DUMP 5-6. page buffer 8-11. 
FIXLNG 7-2. 
INTERACTIVE 193% page size 15-21, 8-10, 
LEAVE 7-3. 
loader parameter 
CONGO 5-9. extents L519; 
ERCNT 5-9 
GO 5-9. parameter references 14-10. 
MAP 5-9. 
NOGO 5-9. parenthesized arguments 15-18. 
NOMAP 5-9. : 
NOMSUB 5-9. PARSE option k=11, 
PEI 5-9 
SYMREF 5=9. PARSE phase i 
LOCK 725% 
MODBCD 7-2. partitioned record 6-4, 
MODMI X 7-25 
NBUFFS 7-2. path See ee 
NDUMP 5-6. 
NOPAC 5-7]. percent fill 8-10. 
NSTDLB 7-2. 
NTAB 1=3 picture decimal point 15-35 
OLEAVE 1-3. 
PRTREC TL PL1 control card jhe 
RECSZ 7-3. 
standard 4-8, PL1 option 5-9. 
STDLBL 7-2 
TAB 7-3. PLINK program oat Rowe 
OPTION control card 2-2, 5=8. PLLINK program 5-15. 
OPTIONS attribute 10-8. positioning Lael, 
major variable li-=2, 
OPTIONS control card he17, member variable 11-3. 
OPTIONS(MAIN) 15-7. precision loss 15-16. 
OPTZ option 4-11, preface cards har ae 
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PRINT control card 6-9. 
PRMFL control card 6-7. 


procedure 
argument list 10-3. 

procedure call 
errors 15-17. 

procedure interface 10-2. 


program construct 
errors 15-1. 


program control 
errors Lod « 


program structure 
errors 15-4, 


programming errors 
examples 15-1. 


PRTREC option 7-2. 
PUNCH control card 6-9. 


quotes 15-5. 


READ control card 6-8. 


record 
dummy 9-1. 
FIXED 6-4, 
partitioned 6-4. 
VARIABLE 6-4, 


RECORD card 
INDEXED file 8-10. 
REGIONAL file S=Dy 


g=11 
8-14, 


record size 
calculation 


record structure 6-3. 
record-oriented transmission 6-3. 
RECSZ option 7-3. 


REGIONAL 
transmission statements 9-2. 


REGIONAL file 

access G=25. 8-11. 
attachment 9-6, 9-7. 
control cards 15-21. 
creation 9-1, 9-10. 
descriptor file 9-6. 
memory reservation 9-6. 
size calculation 9-7. 
structure 9-4. 
utilization report 9-8. 


REGIONAL organization 9-1. 


required boundary 11-2, 11-5. 


restriction 


identifier 15-4. 


root segment Beil. 
RSP DATA card 9-6. 


RSP RECORD card 9-6. 


S* h-7, 
SAVE control card 12-5. 
scale-factor 

conversion Lh=5, 


secondary system standard library 
file 5-2. 
SEC_SYMDEF option b-15, 
5-10. 
5-11. 
5-11. 


segment 
over lay 
root 

segment loading ooo a 

PLINK eg lpo 

PLLINK a agit Mie oP 


SEMANT phase 4-3. 


sequential access 
INDEXED 8-1. 
REGIONAL 9-2, 

SEVERITY option h-1i1. 

SHORT_CALL option ua 15. 


SMESSAGE option h-15. 


SNUMB control card 2-1. 


SNUMBER option ee a 


source program file h—7, 

special option control cards 
special options he T 3S. 
SRCLIB control cards Leo 


SRCLIB input file L2=hy 


SRCLIB program £21. 


SRCLIB work file A2e 05, 


STAB option hemi 2. 
stack frame 
example 
format 
linkages 


Lore os 
LOAB% 
13-9. 


standard calling sequences 


b-16. 


10-8. 


DEO4 


standard option control cards gt ie OP 
standard options 4-8, 
static global variables ABS i 
static variables 14-14, 
STATUS option 4-16. 
STDLBL option f*2: 
storage 
filler cm oe ee 
supplementary 5 is 
storage capacity required k=25.. 


storage space and‘external symbol 
h-21,. 


stranger option file h-6, 
stream data list 14-12. 
stream input-output L4-l1l1. 


stream-oriented transmission 6-2, 


7-4, 


string assignment Le-h. 
SUBSTR 

arguments 15-14. 

varying strings LS-15. 
SVeriTLE contro! card 4-16. 
supplementary storage Lil-3. 


symbol table and cross reference 
4-20. 


SYMREF option Se: Oe 

SYMT option aa! a 

SYSIN bgt Ea 

SYSOUT control card 68, 

SYSPRINT Ses 

system input / output files Pest Oe 
system output file ast 

system standard library file ee 


TAB option 7-3. 


TAPE control card 6-7. 


TAPE7 control card 6-7. 
TAPES control card 6-7. 
temporary work files 1lh-11. 


ce: DEOL’ 


termination | 
abnormal 13-2; 


tests lh-7. 


text cards 5-1. 


TITLE control card 4h-16, 


transfer of control 15-7. 


transmission 6-2. 
record 5~3. 
stream 6-2, 7th, 
transmission statements f" 2% 
INDEXED 8-2. 
REGIONAL 9-2. 


tree 
Overlay 
path 


Sa 
5-14. 


UNALIGNED 1B Gos 


unit of representation 11-2. 


unmatched delimiters 15-5. 


unmatched ELSE clause 15-6. 


unpacked 11-4. 

5-10. 
8-11. 

9-6. 


USE control card 
INDEXED files 
REGIONAL files 


utilization report 
INDEXED file 8-16. 
REGIONAL file 9-8, 


variable 
allocation 15-10, 
BASED 15-12. 
initialization E hbo tae & 6 


VARIABLE record 5-8, 
varying strings La 7 . 
warning message aalZ. 
WK beh 
work file 4-7. 


work regions for files 14-15. 


XREF option h-12. 
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